1. Explain, in plain non-jargon words (nobody cares how smart you are) what problem is being solved, how, and why.
2. Provide contextualized examples (no foobar), not making assumptions about what the reader knows or doesn't know (and avoiding condescending language like "it's easy," "it's common sense" or anything that suggests the reader is "dumb" if they don't get it).
3. Think in terms of a blog post/tutorial, not technical API docs as a starting point. This helps with adoption because people want to understand the thing first and then dig into API (just because you may not doesn't mean that others are the same).
4. Don't be lazy. Show respect for the people taking the time to use your stuff and put in the effort (grammar, structure, quality of examples, etc).
5. Get every step right. Don't make assumptions that the reader knows how to configure something you mention in passing, spell it out. This is especially important if good engineers are writing docs since they leap over little things that less skilled users might not know.
6. Write for translators. Many users don't speak English well and will be running docs through Google Translate. This is a variant of your #1.
7. Consider docs a seamless extension of the product. Use the exact wording and same visual language of the product and make sure docs pick up from where exactly the user was in the product. Evaluate these flows so wherever someone gets tripped up, the right doc is there waiting. Ideally do bidirectional linking so the product itself also links to these.
8. Super consistent language. Figure out your nouns and verbs: someone playing a game is always a 'player' (vs sometimes a 'user' or 'gamer'), someone sending a file is always 'transferring' (vs sometimes 'sending' or 'uploading'), etc. Unless you pay close attention ambiguity is going to creep into documentation.
As someone with English as a second language seeing "foobar" all over the place in lot's of different contexts really confused me a lot early on. Especially when docs started talking about a "foo" and a "bar".
I still don't understand why it is the generic go to word for examples, it makes little sense.
In economics textbooks, companies always produce 'widgets'. https://en.wikipedia.org/wiki/Widget_(economics)
Remind me why I'm here in this document, because I might be in the wrong place.
But in terms of a process. Eg how are you going to keep the docs up to date?
> You might send variables to this server function by calling this endpoint from your javascript code.
You might but in fact you must (or you can) because it is the only way send variables to the server from Javascript. It's not like it's a personal preference or that there is another way.
> You can choose to use `register_rest_route()` to register a custom route [..].
But this is the only way to register a route.
Values (being data) can be transmitted, actual variables (being programming-language constructs to contain values and make them available to operate upon) cannot.
~~There is only one place where this makes sense: in a best-practices section explaining consequences. But also there I want to see clear facts instead of unclear statements making me chase ghosts.~~
Edit: No, just plain facts please.
e.g.
> MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
> You might send variables to this server function by calling this endpoint from your javascript code.
…becomes:
> send variables to this server function by calling this endpoint
…and:
> You can choose to use `register_rest_route()` to register a custom route [..].
…becomes:
> Use `register_rest_route()` to register a custom route [..].
Love the advice overall, and I've tried to apply that as I've been reworking the Redux core docs.
(Gotta say the new name's kinda odd, though.)
It means you can use the same tools (Control Panel, CLI, API) to create and manage cloud applications and their infrastructures on all those different vendors.
The idea is that Divio takes care of infrastructure/DevOps concerns so that customers can concentrate on developing applications and products. https://www.divio.com
Feel free to ask me more.
If you look at a framework like Django. The documentation is generally considered excellent. However now there is simply so much stuff that many complex things get only a cursory treatment. So everybody heads over to SO to find the question that is the closest fit to theirs.
I am not sure what would be better or indeed if there is any solution to this. The framework here layout a multidimensional approach with tutorials to get started and reference to follow up with. However creating documentation systems with that level of complexity is an enormous task and for anything of any quality, an enormous cost.
So what's the answer? I'm not sure there is one.
The article here covers the idea pretty well. You need to cover all 4 parts of documentation, and it should definitely be all available in official documentation, rather than relying on lower-discoverablity third parties.
The question becomes: If I've already put in the work, what cost is there to me to make my knowledge freely available in the form of a SO answer? Usually the answer is "not much".
(I'll be sending you an invoice for this comment)
I’d see those as complementary, and don’t expect documentation to cover most questions/issues you could have.
If I have to create a db with one owner in postgres, I will not use the postgres docs.
Documentation fulfills five important functions:
- Communications to management about the progress of
the project, providing intermediate product
visibility
- Task-to-task communication
- Instruction and reference
- Quality assurance support
- Historical reference
For certain types of documentation you need technical technical writers - for example, see http://hackwrite.com/posts/enough-to-be-dangerous/. And you need a proper content strategy / information architecture in place. Blame your recruiting managers and whoever wrote the job descriptions for not thinking about that.
Edit: And of course you need to allocate developer time. It's called knowledge transfer.
The only quadrant that can be a bit challenging is the explanation: some projects are just relatively straightforward and don't require a lot of background knowledge about the whys. In that case, I've found it best to just stick to a couple of lines on the homepage explaining the project's background and the problems it's solving, rather than a separate, rather barren-looking section of your docs.
Usually, I realize it is because it's following whatever is my framework's way of doing things, or it is following the usual specs of the tools I use. In this case, I make a conscious effort to dig up a link to a tutorial on a "standard project", and link it there, an example would be:
> This project is following a Classic Java Spring Architecture (-> links to the spring tutorial), with this and this modification...
You have to imagine that people happening upon your documentation might have a totally life experience than you, they may even be a lowly intern, thrown to your project as the sole maintainer of your code, with only school-taught experience.
The scheme is not a plan that must be fulfilled, it's a guide or map to help you see where you are and where you need to go.
However, don't be ashamed of barren-looking things. They are OK. The reader won't mind.
It now has its own domain, because it's about time. This is where it will continue to be updated and maintained.
A quick clarification: I am still at Divio, but after a break in June I'll be looking for something new.
If you have a notable product, a large developer user-base, a positive internal culture, and need to address some significant challenges in developer education/documentation, at the highest level - get in touch: daniele@vurt.org
I should also like to point out that when I posted this a week or so ago, it got just three points https://news.ycombinator.com/item?id=26724825. Very unfair.
To be fair, when the article was posted under its Divio url a year ago it got 717 likes and 199 comments - https://news.ycombinator.com/item?id=21289832
I'll not repost the comment I made on that thread (because: too many spammy links) but the advice in the article is good; I wish more people would follow the recommendations.
Best of luck with the job hunt..!
I'd think tutorials would fall under theoretical because if it gets too practical, are you not effectively writing a how to guide?
I'm not really sure the four categories fit into that quadrant scheme as well as they'd like.
It's not theoretical knowledge in the sense of "theoretical/applied physics", but rather theoretical knowledge because there is an extra step between it and application.
So if I give you a list of functions in a module/class and just tell you what they do, that is more theoretical than a code block that you can cut and paste as running code.
I'm not sure how else you would label this axis, theory/practical seems just fine.
Practical knowledge is knowing how to do something - tie your shoelaces, instantiate a model class, authenticate to an LDAP server.
Theoretical knowledge is knowing what is the case - that the cross-flow valves must be closed at take-off, that everything in Python is an object, what a Python property decorator does.
Technical reference is theoretical knowledge (that you apply in practice), as is explanation. Tutorials and how-to guide contain practical knowledge.
Instead, and I mean to eventually write this long-form, I find it a lot more useful to think of documentation as a learning experience. You need several levels: for those who don't even know they want to learn it, for the beginners, for the seasoned that need a quick ref, for the ones who just lack practice, etc. In this way, tutorials will cater for a specific type of learners while the API docs will be a reference for those with already experience.
That is why I will also argue that library authors tend to go to the API docs. I read the docs of my own libraries, so while I have a feeling how it works I might want to quickly check the format of e.g. the second options argument. Since I wrote it, it's very useful for me to document the API since I already know how to get started or why to even use it. But that's not the same for others.
So I will argue that from the landing page (if any) to the API docs, there's no a strong divide and you should start teaching the user from the beginning. As an example, my projects tend to include a few-lines snippet as soon as possible.
PS, to do great documentation is a full-time job, and I still maintain that some ideal-ish ratio of lines of code vs testing vs documentation, given all the time in the world to work on it, is 1:5:10. as in, for each 1 line of code there should be 10 lines/paragraphs of documentation.
I would had to the mix a page where jargon is defined, like a lexicon. You cannot, and should not always get away with jargon. Sometime you should (beginner tutorial), sometime you should define it inline (advanced tutorial), and sometime you should just use it (references), but with link it to the definition.
If you are in a rush, the diagram is all you really need. The lecture is needlessly long, even played at double speed.
"It should exist".