The blog of Divio, a Django hosting and platform company, known for its writing on software documentation structure.
HN commenters recommend its four-part documentation framework (tutorials, how-tos, discussion, reference) as among the best writing on docs, and mention Divio's hosting.
While I think there is great benefit in using concise and clear language, I highly disagree if anyone takes away the idea their documentation should be a themed after an RFC (I do enjoy reading RFCs though!)
This [0] was imo an excellent discussion on documentation that gets to the issue much more than word and formatting choices.
The short is there isn’t “documentation” as one thing, but four.
1. Tutorials where you start to finish explain it to a newbie,
2. How to guides where you explain specific tasks,
3. Discussions where you lose all formal pretext and explain your INTENT (huge) and reasoning for decisions, like you would actually explain to a person, not a robot, not some cute marketing talk
4. Technical reference that goes over the actual mechanics and the weeds that people need only once they’re working with your solution.
It was on HN at least once.
[0] https://www.divio.com/blog/documentation/
> Instead, I recommend starting by documenting the key behaviour of the program, describing its model of the world and defining terminology, and only then trying to document each function in terms of that model and terminology.
Can you explain in more detail how that's different from the approach described in "What nobody tells you about documentation"? [0] At first blush, your recommendation sounds pretty similar to what is suggested in that post.
Is this a critique of the guideline to "Give reference documentation the same structure as the codebase" that was in [0], or is it more like you think the importance of the "Explanation" section is underrated?
(This is coming purely from the perspective of somebody who is trying to write better documentation. I'm not trying to defend any particular stance, just interested in your opinion.)
[0]: https://www.divio.com/blog/documentation/
I read an article[0] on HN[1] recently — it talks about the different types of documentation. To quote it directly:
"Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all."
I agreed with its premise — I've found things that only have "story format" docs (i.e. explanation / how-to guides) to be really frustrating. On the other hand, if all that's available is a deep and highly particular technical reference, it's really difficult to get started sometimes.
[0] https://www.divio.com/blog/documentation/
[1] https://news.ycombinator.com/item?id=21289832
> I need to see practical examples
And I need to see diagrams of mental models, though practical examples help solidify that. So one challenge with writing documentation is knowing what your audience needs. A better taxonomy of documentation would help solve this. For now, here is one I like based on https://www.divio.com/blog/documentation/
- Tutorial: A walk through how to learn the basics as you build something.
- Explanation: Showing the mental model of something
- Guide: A walk through how to solve a specific problem
- Reference: A comprehensive* listing of the API capabilities and how they are used.
-------
If anyone knows of some good tutorials or explanations of mobile programming with React, I'd be grateful for recommendations.
Divio offers a "platform as a service" for django, Django CMS, Wagtail, and Oscar commerce projects:
https://www.divio.com/
However, they lack a basic support ticketing system on the lower-tier price plan. It is also not obvious if/how you can deploy a pre-existing app from an arbitrary Git repo, as their service is geared to use Divio project scaffolding (including their own SSO).
While the Divio service seemed appealing at first, the above issues are a bit disappointing (and it has been nearly 24 hours with no response, since I contacted their support.) Overall, Divio seems to leave a bit lacking when compared with other hosting options like WebFaction (a shared hosting provider with good Python support.)
https://webfaction.com
I think there can be different types of documentation (tutorials, reference, explanation, how-to guides). I came across this article a while back that goes over different categories and always re-read it when I know I'm going to have to write a bunch of documentation for something and always find it helpful to really think about the type that I need to write. In regards to the poster you replied to I think Oreilly books are in the explanation category of documentation instead of the traditional reference kind found online.
The article I'm referring to: https://www.divio.com/blog/documentation/