Timeline for Tearing Down the Structure of Documentation
Current License: CC BY-SA 3.0
21 events
when toggle format | what | by | license | comment | |
---|---|---|---|---|---|
May 29, 2017 at 14:33 | comment | added | Peter Taylor |
I understood that reference documentation was the main point of SO's Documentation project, because so much first party reference documentation is along the lines of "Foo Foo { get; set; } : gets or sets the foo", which tells me precisely nothing.
|
|
May 29, 2017 at 10:05 | comment | added | Code4R7 | True, the main problem of Documentation is a unified context. There is no such thing as "one size fits all", even for the templates mentioned, because readers are not the same. Think about different skill levels, interests, cultural differences. Q&A is without such a structure, like Wikipedia. | |
May 29, 2017 at 7:50 | comment | added | kayleeFrye_onDeck | I'm all for multiple documentation structures, or at least classifications when browsing Documentation pages to help me find the type that I want. | |
May 22, 2017 at 19:08 | comment | added | jinglesthula | I've always appreciated thorough API docs. But I've never seen good API docs (thorough or otherwise) that didn't include examples. That said, Documentation seems to surface examples devoid of the context that well-organized (and thorough) API reference documentation gives. | |
May 21, 2017 at 15:10 | comment | added | DavidG | I think the idea of different types of docs is exactly what is needed. Rather than sticking with one type though, why not have options. For example, c# could have reference, tutorial and task-oriented document sections quite easily. So perhaps a menu of types per tag would work? Addressing this and then quality of content, and I think this will be a viable platform, perhaps even one where library authors would consider using as the primary source. | |
May 19, 2017 at 15:52 | comment | added | Frank | Yeah, in my opinion, it's too ambitious; and even if good roadmapping works for maintaining some tutorials, it crowds out others who have a different perspective on how to tutorialize a topic. The less ambitious target of handling the other cases (that you mention in bold above) seems like a hard enough job for Docs.SO already. | |
May 19, 2017 at 15:44 | comment | added | Monica Cellio | @Frank I've been part of multi-author projects like that, but the key is that there's a roadmap up front. If each person is just doing his own thing it's as you say; if there's someone leading the effort or sufficient structure for the community to lay out and record their plans, and some sort of monitoring, it can work with multiple writers. It is harder, of course. | |
May 19, 2017 at 15:35 | comment | added | Frank | I don't think (multi-example) tutorials are compatible with collaborative editing. Everyone has their own ideas about what examples are appropriate and the order in which they are given. Of course, broad tutorials are likely to get praised on twitter, but long-term, no one can maintain them but their original authors; and late-comers who think concepts should be introduced differently will be accused of duplication if they make their own tutorials to their liking, or of vandalism / edit warring if they rework the first-mover tutorial. | |
May 19, 2017 at 14:53 | comment | added | Monica Cellio | @Rhayene yes, agreed -- a mature doc set needs all of: tutorials that cover the basics, rich documented examples that are more advanced (as your knowledge increases you need less of a tutorial style, though elements remain), conceptual documentation that among things enables you to reason for yourself about stuff not covered in examples, and complete reference documentation. A lot of doc sets skip the middle two -- and then they skimp on the reference doc, leaving people wondering "so you did 101; where's 201 and 301 and...?". | |
May 19, 2017 at 14:08 | comment | added | Rhayene | I understand @Suragch s point. Tutorials often only cover the simple use cases. Often enough you have some kind of disconnection between understanding the simple cases and understanding the finer points up to the functionality you need. Connect that with very sparsely written or not existing API Docs and you are stuck. So for me the problem seems to be that both kind of documentation are missing pieces. | |
May 19, 2017 at 3:35 | comment | added | Draco18s no longer trusts SE | @MonicaCellio I figured (generic) you wouldn't know the topic. So no worries there. | |
May 19, 2017 at 3:33 | comment | added | Monica Cellio | @Draco18s yes, something like that. (I don't know your topic area at all, so I'm just commenting on structure.) | |
May 19, 2017 at 3:29 | comment | added | Draco18s no longer trusts SE |
Even better if it can be sketched out early on, before all the pieces exist! Say, like how I handled this topic? I wanted to have a "Stat here" sort of index and branch off into the two major areas with a few common topics highlighted and links, providing some organization.
|
|
May 19, 2017 at 3:20 | comment | added | Monica Cellio | @Suragch that initial learning is probably best addressed by concept and tutorial docs, though. Then when you need to know about that one parameter that's relevant for this weird corner case that doesn't rate tutorial coverage, you'll have the background you need to dive into the reference doc and get your answer. Starting with reference doc is not a recipe for success in my experience. | |
May 19, 2017 at 3:16 | comment | added | Suragch | In order to remember what a function does, one needs to have learned it before. I would be pleased to see a bit more explanation and examples for that initial learning. | |
May 19, 2017 at 3:09 | comment | added | Nicol Bolas | @Suragch: But reference documentation is for experts. Or rather, it's for people who have an idea of the concepts already, and just need to know what the functions do and what the parameters mean. It's for someone who's already familiar with the system. Reference docs are intended to be technical and comprehensive. They are not intended to be learning materials. From a quick skim of that link, it seems decidedly... adequate in quality. It's not meant for the neophyte; it's meant for someone who needs to remember how that one function works. | |
May 19, 2017 at 2:34 | comment | added | Suragch | @NicolBolas, As an example, take any one of the constructors or methods of Android's StaticLayout. This type of documentation may be enough for expert programmers like you, but it is severely lacking for someone who is learning like me. By comparison, Android's explanations on broader conceptual topics (like Layouts) is quite good. | |
May 19, 2017 at 0:00 | comment | added | Nicol Bolas | @Suragch: Really? Because my experience is essentially the opposite. I can find reference documentation for pretty much any API in the languages I use. But conceptual explanations? Those are much harder to come by. Until I wrote most of the OpenGL Wiki, you couldn't find any of those concepts explained effectively online. By contrast, you could find the ARB's reference docs for OpenGL functions. Now, that doesn't mean that it was good reference docs. But if you want to find out what the parameters of a function do, you usually can. | |
May 18, 2017 at 23:14 | comment | added | Suragch | What I need the most is reference documentation. I can find tutorials, conceptual explanations, and step-by-step guides around the internet. However, I've had countless experiences of needing to use (or at least understand) an undocumented (or poorly documented) API. Often my only recourse is to laboriously analyze the source to see what it does. | |
May 18, 2017 at 21:11 | comment | added | Nicol Bolas | I think this is the most important question we need to decide on before we start building structure. What kind of documentation do we want to encourage? I went into detail on the needs of different forms of documentation way back on the original Warlords of Documentation post. | |
May 18, 2017 at 20:42 | history | answered | Monica Cellio | CC BY-SA 3.0 |