Divio Blog

That's really great to see it used in Gatsby's documentation, I wasn't aware of that. And I like the way you say e.g. "Practical step-by-step guides to help you achieve a specific goal. Most useful when you're trying to get something done." under each heading, it hadn't occurred to me that it would be good to state that explicitly like that. To complete the circle, https://divio.com is built in Gatsby (not the documentation though; that's in RST/Sphinx and published on readthedocs.com).

One of the best articles I've seen on writing documentation is "What Nobody Tells You About Documentation" [0]. It divides docs into four categories: Tutorials, How-To Guides, Discussions, and References. I'm currently working on a major rewrite of the Redux core docs [1], and I've been taking notes on that post and various other docs writing resources [2] so I can apply them to the rewrite. [0] https://www.divio.com/blog/documentation/ [1] https://github.com/reduxjs/redux/issues/3592 [2] https://github.com/reduxjs/redux/issues/3609

> 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.

> 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/

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

Sphinx? mkdocs? Also worth thinking about how you should document it. Really great talk about this by Daniele Procida: https://www.youtube.com/watch?v=azf6yzuJt54 Prose version of the talk: https://www.divio.com/en/blog/documentation/

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/

These might help: * https://github.com/jenniferlynparsons/awesome-writing * https://www.divio.com/blog/documentation/

At the end of this article the author links to and mentions the four types of technical documentation: https://www.divio.com/blog/documentation/ I’ve found this to be especially useful when writing documentation. If you don’t think in this way them your documentation may end up being an impromptu blend of more than one type, and hence may not be useful for a specific use case. Instead I try to structure the documentation for one of these.

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

This could be "How to write good project documentation" in GitHub. I prefer the more general approach to documentation given here: https://www.divio.com/blog/documentation/

I'm writing software documentation at the moment, and having watched this will I'm sure make it 1000x better. It could be called "How to write good documentation - everything you need to know". Thank you Daniele! and to HN for mentioning it. webpage here: https://www.divio.com/blog/documentation/

This documentation is very impressive. I like that the author included a link to "Why is the documentation structured this way?" [0]. 0: https://www.divio.com/blog/documentation

I quite like this framework from Divio[0] for thinking about how to write documentation. It mainly gets you thinking about the _purpose_ of your documentation (and therefore the audience). [0] https://www.divio.com/blog/documentation/

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/

I like the guys at Divio[1] (of Django CMS fame). They have a partner program if you are hosting for your clients. [1] https://www.divio.com/en/