41

I was making a couple of updates to the HTML documentation and realised that I wasn't clear on exactly who the audience is meant to be. If it's introductory material how introductory should it be? Should we, for example, provide an 'anatomy of tag' type explanation that's targeted at the lay person? Or should we assume that most people 'get' the principle behind tags? I guess if such an explanation did exist it would be best off in the Remarks section? This seems to be the approach taken by the Git documentation, which uses Remarks to give some history and background.

3
  • 46
    This is possibly another argument in favour of heeding Jeff Atwood's advice and calling the whole thing "Examples" rather than "Documentation". A collection of examples can be targeted at all levels of experience; the target audience is inherent in each example. Order them by level of difficulty, done. A real documentation needs a voice, some amount of editorial oversight, and a defined target audience.
    – Pekka
    Commented Aug 12, 2016 at 10:44
  • 2
    It may be that this question answers mine: meta.stackoverflow.com/questions/329179/…, particularly "people do not visit Documentation to get background information on a certain topic". But I assume there's some divergence of opinion on this and I'd love to hear who SO think the audience should be.
    – Willl
    Commented Aug 12, 2016 at 11:31
  • 14
    Since there is no knowledge requirement what so ever to post examples, the same applies to the readers. In fact, given the quality of most Documentation examples so far, I think you can even assume that the reader has less knowledge after reading the article, than they had before they did.
    – Lundin
    Commented Aug 12, 2016 at 14:17

2 Answers 2

12

The way that I use documentation would be to review a certain topic that I don't have a particularly strong grasp of, but I have at least the basics down. Therefore, I think that documentation is more suited towards those that already have a grasp of the materials as, otherwise, it would get bogged down in explaining every little detail. I see no problem in utilizing remarks if a concept does indeed need a little more explanation.

7
  • I think it's easy to assume the reader knows a lot already, but I would be hesitant to see SO documentation put off beginners because something that is easily explainable isn't explained. Programming can seem daunting enough as it is when beginning, I would rather see things made clearer for a wider audience, for the sake of a few keystrokes.
    – Harry
    Commented Aug 12, 2016 at 18:36
  • 6
    @Harry SO isn't really for "beginners" in general (not that the beginners seem to understand this judging by their questions...). There is certainly a balance to be struck, but explaining everything just adds a bunch of noise to the information that really needs to be exposed. Commented Aug 12, 2016 at 18:48
  • 5
    Of course it is for beginners. It is for programmers of all skill levels. What it isn't is for people who expect someone else to do all of their work for them. If you aren't willing to help yourself, then we will not hold your hand. @bradley
    – Cody Gray Mod
    Commented Aug 13, 2016 at 12:59
  • 1
    @CodyGray: Ok, but where do we draw the line between beginners and people who haven't even begun yet? e.g. the x86-32 asm Linux Hello World example required a huge amount of explanation, but still probably isn't clear to someone that doesn't know C or Unix at all, or the concepts of registers and memory. Not knowing anything about the audience makes me feel like everything I write has to explain everything from scratch, which is exhausting and overwhelming. Commented Aug 14, 2016 at 1:31
  • Off-topic: I ended up adding so much (and rewriting basically every comment) that I felt like I maybe should have rejected the edit that added the original lower-quality (IMO) version which prompted me to spend time on it. Commented Aug 14, 2016 at 1:33
  • 1
    @peter Confession time: I said that Stack Overflow was for all skill levels, and when I think of Stack Overflow, I still think of Q&A. I'm honestly not sure about Documentation, or how it fits into that. The problem is that the format is just not conducive to writing tutorials. It seems to want to force you into dumping code snippets, which used to be what the Stack Overflow people said its purpose was (a collection of examples), but now they are denying that.
    – Cody Gray Mod
    Commented Aug 14, 2016 at 7:19
  • You would have to write a whole book to explain assembly language programming, and indeed many people have done that. I see no way, nor any purpose, for us to replicate their volumes of effort here.
    – Cody Gray Mod
    Commented Aug 14, 2016 at 7:19
4

Many of the documentation tags have topics meant to be introductory. If you're editing one of those, information like the anatomy of a tag would be appropriate. If not, then I would assume they have at least a basic grasp of the language.

Moreover, there are some topics where typing at a beginning-programmer level would be inappropriate, like event-driven programming or regular expressions, because most often, beginner programmers will not be ready for that yet.

What I think would be more helpful for all levels and less intrusive for more advanced programmers, though, would be to start each page with a "concepts you need to already know for this to make sense" section.

2
  • 1
    I really like the last paragraph. But that still leaves the question of how you choose which knowledge to require. It's pretty obvious that some topics should be more basic than others, but what can you assume about related topic? e.g. does an assembly language example assume that people know C? Or Unix? And even within the subject matter, how basic do you make an example that should be basic? It's not a binary thing, where an example is either "basic" or "advanced". I guess with good headers, people can find examples that suit their set of existing knowledge Commented Aug 14, 2016 at 1:42
  • All good points. Thanks. I'm now wondering if the issue is partly a user experience one. What we have right now is a list of examples within topics but the introductory topic is often heavy on the background and light on the examples or requires a lot of explanation up front (see e.g. - stackoverflow.com/documentation/x86/1164/introduction-to-x86/…). Maybe what's needed is a sort of 'meta' section for each tag that provides background and required knowledge so the examples themselves don't get muddied.
    – Willl
    Commented Aug 15, 2016 at 8:23

Not the answer you're looking for? Browse other questions tagged .