I've been raising this question occasionally in comments for a while now, but I thought it was worth asking it as a Meta question: just what's the point of Documentation? What niche do the development team intend it to fill? How do they envisage a reader using it?
Let's consider some existing sources of information for programmers, and the role they fill. Stack Overflow Q&A helps people get information they need in two simple ways that we clearly understand, and has done since its inception:
- People can ask questions about real problems they have and receive answers, immediately helping the asker
- So long as questions are generic enough and their titles are clear enough, people with problems can easily Google them and find the answer to their exact problem
You can of course argue about which of these mechanisms is more important and fundamental to how Stack Overflow operates (correct answer: it's the second! it's the second!), but I think we're all pretty clear that they're both there and that they both broadly work.
Of course, Stack Overflow Q&A has several innate weaknesses:
- Since any old idiot can write or vote on an answer, without needing to be affiliated with the language or library they're writing about, a reader never has any real guarantee that what they're reading is or ever was accurate (unless the answerer thoroughly evidences his claims by showing the results of experiments or by referencing a more reliable source)
- Since nobody is responsible for "maintaining" Stack Overflow answers, even answers that were once accurate may be obsolete by the time a reader arrives
- While there are many "How do I do X?" questions on Stack Overflow, there are few "What does function X do?" questions - it's a powerful tool for doing a task -> function lookup, but not a useful one for looking up how a function behaves
Let's consider other sources of knowledge. What's official documentation (with a small 'd') useful for? How does it help readers? Well, I can think of a few ways:
- Since it's "official" (i.e. written by the people who wrote the code, or those close to them), the vast majority of information is likely to be accurate down to the most pedantic detail. This makes it useful either for a reader who wants certainty about how something will behave, or a reader who wants to cite a reliable source elsewhere (like in a Stack Overflow answer)
- It provides an easy and fast mechanism for looking up how a particular API behaves (and typically documentation on a particular API can be immediately found by e.g. Googling for the function name)
- It provides a way to browse and explore the capabilities of a language, tool or library, in order to build up a comprehensive understanding of what it can do
But offical docs also have deficiencies that prevent them from being the One True Source of Knowledge for Programmers:
- Not all tools have them (or else they may have been hastily written by somebody with a poor grasp of English)
- Since information in documentation is usually structured on a per-API basis (rather than a per-problem basis like on Stack Overflow), if you're in a hurry and don't have time to read an entire manual then you usually need to know the name of the function/class/endpoint/operator you're looking for in order to search for information about it - searching for the task you're trying to perform or the error you're encountering frequently won't return useful results
So, we've got two information sources already out there with their own innate merits and weaknesses. How about Documentation (with a big "D" this time)? What are it's strengths? What are its weaknesses?
Well, I can certainly articulate some weaknesses - since Documentation has all the major weaknesses I just listed of both Q&A and official docs - the two sources of information that I make the most use of in my professional life:
- Any idiot can write it and vote on it; there's no guarantee of quality or accuracy
- There's no guarantee of maintenance; information may be obsolete
- Since it's example-based, you can't look up a function and read a detailed description of its behavior
- Plenty of stuff just isn't Documented
- It's close to completely unsearchable. I've never seen Documentation in my Google search results, and the internal search is very poor.
I've tried, sincerely, to find a way to make use of Documentation, but I just can't see how. Recently I learned about Python's async
/await
syntax. Let's compare my experience using the channels I'm comfortable with, versus what I would have experienced if I'd tried to use Documentation, and reveal some of the ways that it sucks in the process:
The non-Documentation way
- I Google
async await python
via my URL bar - I open some relevant docs that come up as the first result in a new tab
- I open a lengthy blog post explaining the concept and start skimming. The blog post quickly explains that
asyncio
is "an event loop framework which allowed for asynchronous programming" - cool, I roughly know what that means - and gives me a rough explanation of what a "coroutine" is. Okay, that's cool. - I change tab and have a look at what the docs say. They're not great introductory docs, but sweet, there are some examples I can copy and paste showing the usage of the
async
andawait
keywords. They're kind of bad examples, though; they don't show any sort of concurrency, there's only ever one of these "coroutine" thingummies in play at a time. How do I run coroutines in parallel? - I Google
asyncio wait for multiple coroutines
- The top three results are Stack Overflow questions pointing me to the
wait()
,ensure_future()
andas_completed()
functions. Boom, that's enough for me to start writing something useful, and I can learn more as I go.
Plenty has gone imperfectly in this process. I wasn't sure what resource to initially start reading. Both sources I picked had a lot of waffle that I didn't really have the patience to read through when I'm just trying to 1) get a basic gist of what the heck's going on and 2) figure out if the source itself is useful to me. The official docs had crap examples that failed to illustrate the fundamentals of the feature I was reading about, so I had to bounce between different sources. Can Documentation do better?
The Documentation way
Since Google doesn't return Documentation results, let's go there manually:
- I go to https://stackoverflow.com via my URL bar's autocomplete
- I click "Documentation"
- I click "Python Language"
- I CTRL-F for "async". There are no results.
- Wait, there are 9 pages of topics? No wonder CTRL-F didn't work. Let's use the search function.
- I search for
async await
. The top result is something (presumably irrelevant, going by the information displayed to me) about websockets - WTF? At the bottom of the results there's something about "Asynchronous Executors", though - that sounds related! I open that. - It sucks - the Example uses concepts like "asyncio" and "executors" without explanation even though this is my first time encountering them, and then gives me a useless "Hello, World!" example that doesn't show me how to run anything in parallel. But at least I've now stumbled onto the asyncio module topic, which didn't show up in my search results
- The Example at the top of the page actually contains (in its third code block, after some confusing examples that tell me to do "time intensive stuff" inside
async def
fed functions) a reasonable example of howasyncio
can be used. Unfortunately, if I were really a beginner arriving here, I wouldn't have the basic grasp of what the feature I was reading about was to be able to recognize that or understand what was going on - and that's it. That's all Documentation has to offer. At this point I'd need to give up and use Google; the entire process of using Documentation here was a waste of time.
The non-Documentation path to wisdom was a little bumpy and it's possible to imagine a shorter route, but at least I got there. Using Documentation was also a slow and bumpy process - it took me 4 page loads to even see some search results, heaven's sake, compared to 1 when I Google via my URL bar - and in the end, the information I needed simply wasn't available in Documentation. There were only unexplained "Examples" that couldn't possibly make sense unless I read another source of information (which would likely contain similar examples anyway, because, y'know, Stack Overflow answers and official docs generally contain examples - just with sufficient context and explanation to be able to understand them, unlike the random code dumps I found in Documentation).
And so I return to my original question: what's Documentation for? How am I supposed to use it, as a reader who is seeking information? In what circumstances would I benefit from Documentation existing, given that I already know how to use official docs, Stack Overflow Q&A, and Google? What are its strengths, relative to little-"d" documentation or Stack Overflow's existing Q&A? What's the envisaged user story that somehow involves me ending up reading a piece of Documentation and finding the information that I needed?
At the moment, it seems very clear to me - and most of the community - that Documentation is inferior to other existing sources in every way, to the point that it might as well not exist. If that's going to change, the users authoring it need to be given some clear vision of who is going to use it, and how, and what characteristics a Topic or Example needs to have to serve those ultimate use cases. Until then, you're just going to be stuck with the mess you have now - a collection of contextless code dumps, upvoted by other people contributing contextless code dumps, all entirely useless to anybody.