Top all-time · #2862
divio.com
Company blog · divio.com/en/blogprogrammingweb
divio.com is the company blog at divio.com, writing about programming and web. Since 2016, 25 different Hacker News readers have linked it 40 times, most often “Four kinds of documentation”. No feed was found, so read it on the site itself.
Too few sampled comments (20) to say how often HN recommends it.?
Why HN links it
HN readers link divio.com's documentation post, which splits docs into four types: tutorials, how-to guides, explanation and reference. Commenters use it to plan and judge documentation by purpose and audience.
Summarised by Claude from a sample of 20 HN comments that link here. Each comment is marked recommending, critical or neutral (citing without judging); how this works.
Most-linked posts?
- Four kinds of documentation16 people · 18 mentions · first linked 2018-09-23
- What nobody tells you about documentation4 people · 6 mentions · first linked 2017-05-23
- Show HN: Free Django Hosting with SSL, managed database and custom domains2 people · 2 mentions · first linked 2016-08-11
What Hacker News says?
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 docum…
Comment linking /
on “A Framework for Writing Better Documentation”Submitted Four kinds of documentation as a story · 717 points
HN discussionThis 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
Comment linking /blog/documentation
on “BrachioGraph – a cheap, simple pen plotter”Submitted What nobody tells you about documentation as a story · 37 points
HN discussionAt 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 document…
Comment linking /blog/documentation/
on “Notes on Technical Writing”Submitted Scaling the peaks of Hacker News as a story · 18 points
HN discussionI 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 di…
Comment linking /blog/documentation/
on “GitHub Actions is my new favorite free programming tool [video]”Submitted Show HN: Free Django Hosting with SSL, managed database and custom domains as a story · 18 points
HN discussionA lot of being productive as you gain more experience is by working on the right things, so you produce more with same amount of effort. What this means is you want to start with figuring out goals. What is the project's goal? What are the constraints? Why are things being done the way they are? What does success mean? Once you know that you can start doing tactical stuff (and since answering those questions can tak…
Comment linking /en/blog/documentation/
on “Ask HN: How do you become productive in a new project as a senior developer?”Submitted What Keeps Programmers Happy? as a story · 9 points
HN discussion> 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.…
Comment linking /blog/documentation/
on “Ask HN: What do you regret you didn't know when programming for iOS or Android?”Submitted Django deployment made as easy as ABC (and PHP) as a story · 6 points
HN discussionI 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 b…
Comment linking /blog/documentation/
on “Why There Will Never Be Another RedHat: The Economics of Open Source (2014)”Submitted Seven principles that shape customer experience at Divio (and why they work) as a story · 3 points
HN discussionThis is probably getting a bit detailed for a Hacker News thread, but I'd be happy to take this elsewhere. Your feedback has been very helpful and is much appreciated. We're on https://www.divio.com/en/#intercom amongst other places, but that's the easiest way to speak to us directly if you like. Thanks again.
Comment linking /en/
on “Making Django CMS as easy to install as WordPress”Submitted What nobody tells you about documentation as a story · 3 points
HN discussionIf you're having any trouble getting to grips with it, don't hesitate to drop us a line - on our live help system if you wish: https://www.divio.com/en/#intercom Otherwise, both https://www.django-cms.org/en/blog/2016/02/16/build-a-websit... and the Guided Tour https://www.divio.com/en/academy/aldryn-cloud-django-cms-gui... will help.
Comment linking /en/academy/aldryn-cloud-django-cms-guided-tour/
on “Making Django CMS as easy to install as WordPress”Submitted What nobody tells you about documentation as a story · 3 points
HN discussionWhile 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 yo…
Comment linking /blog/documentation/
on “Must and Must Not: On writing documentation”Submitted What nobody tells you about documentation as a story · 3 points
HN discussionI 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/
Comment linking /blog/documentation/
on “Ask HN: What is key to good technical documentation?”Submitted What nobody tells you about documentation as a story · 2 points
HN discussionDivio is a cloud management/application hosting platform. We use Docker for containerisation, and provide a unified integration layer to multiple different underlying vendors (AWS, Azure, etc). 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 concer…
Comment linking /
on “The Grand Unified Theory of Documentation”Submitted What nobody tells you about documentation as a story · 2 points
HN discussion> 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 t…
Comment linking /blog/documentation/
on “Essential elements of good documentation”Submitted The future's looking more Pythonic than ever as a story · 2 points
HN discussionhttps://www.divio.com/blog/documentation/
Comment linking /blog/documentation/
on “Essential elements of good documentation”Submitted What nobody tells you about documentation as a story · 1 points
HN discussionThis 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/
Comment linking /blog/documentation/
on “Essential elements of good documentation”Try them all! They take different approaches, and one might suit you better than another. django CMS has addon applications for both jobs (Aldryn Jobs) and weblogs (Aldryn News & Blog). If you're interested, you can join a free Guided Tour each week that will actually cover some how this all works in django CMS: https://www.divio.com/en/academy/aldryn-cloud-django-cms-gui... For a fully-blown jobs site by the way yo…
Comment linking /en/academy/aldryn-cloud-django-cms-guided-tour/
on “Django CMS version 3.3 has been released”
