The Surprising Power of Documentation
vadimkravcenko.com
The Surprising Power of Documentation
1–10 of 153 posts
Re: The Surprising Power of Documentation
#2It's hard to argue with, especially if you've experienced using good documentation. OpenBSD's man pages are one example. It takes a little time to break the habit of checking Google first and instead checking the man page first (you eventually learn that you rarely need more than that).
The key word is "good" documentation. That takes time and effort to write, and it takes time and effort to keep it updated as things change. As the author notes, it will have to be something that is made part of the culture of the organization. And given that recent agile programming approaches proclaim that "the code is the documentation" and that formal, separate documentation is an impediment to productivity, you'll find that many developers will dig in their heels if asked to write documentation.
Bad, outdated, or just plain wrong documentation can be worse than nothing, as it tends to lead you to incorrect conclusions and beliefs about the system.
Re: The Surprising Power of Documentation
#3It's hard to argue with, especially if you've experienced using good documentation. OpenBSD's man pages are one example. It takes a little time to break the habit of checking Google first and instead checking the man page first (you eventually learn that you rarely need more than that). The key word is "good" documentation. That takes time and effort to write, and it takes time and effort to keep it updated as things…
All of the above. But as someone who writes documentation let me add, most programmers are bad writers.
To write good documentation you need to mix technical reference (the easy part) with user reference. The latter requires you to imagine where the user is at, and take them to where they understand. This is hard to do, and requires well, skills.
So a culture of documentation is great, but quality matters as much as quantity. Clarity, completeness and coherence are all legs of the stool.
Re: The Surprising Power of Documentation
#4100% this. And yes, good documentation takes a lot of investment but it pays off like compound interest. But with that done, it becomes even more important not to pull the carpet for no good reason, you are building a tower and documentation is at the foundation.
We’ve built Lowdefy [1] as an open source project and documented it with all effort, 200 pages of docs. I often forget why or how something works and then jump to the docs. This investment keeps on paying of as we use Lowdefy to build customer apps, new devs in the team typically take less than two week to get up to speed and start making contributions, the sharp ones, just a two or three days.
This year, we’re extended our documentation onto customer apps aswell, with flow diagrams, state machine definitions, detailed field level explication schema definitions, and end user test procedures. The key here for this documentation is detail. It should be easier to reach for the docs and the the answer, than to dive in the code and interpret it.
Re: The Surprising Power of Documentation
#5100% this. And yes, good documentation takes a lot of investment but it pays off like compound interest. But with that done, it becomes even more important not to pull the carpet for no good reason, you are building a tower and documentation is at the foundation. We’ve built Lowdefy [1] as an open source project and documented it with all effort, 200 pages of docs. I often forget why or how something works and then j…
It is important to add to this a culture of actually reading the docs. Kudos here to my co-founder Sam. First developer I’ve ever met that reads ALL the docs before touching a line of code. When we say let’s pick up some tech, he dives in and reads every page of doc he finds. The effect saves time and results in much much better technical decisions. You don’t get stuck in the unknown, you immediately know where to go look if you are unsure, and architect a better big picture.
This, given of course that the tech you are picking up has good docs.
Re: The Surprising Power of Documentation
#6This is too biased for-docs IMHO*. I do agree with many points, documentation IS amazing, and you are very likely under-documenting things in your company. But documentation is not cheap to create, and specially it's not cheap to maintain. If you are not writing enough yes, sure, that's probably a great investment, but start bit by bit.
I've worked in multiple* companies where the problem was too much documentation, and of course everyone was afraid to update or ghasps* remove any piece of old documentation in case it was still useful. Imagine working on a codebase where 80% of the code was unused or commented out but no one dared changing it just in case (flashback to 2010 with 4000 lines of style.css).
I'd suggest to take a more holistic approach and treat documentation a lot like testing; for that prototype, probably just write the barebones documentation, for the production-ready new feature go all-in and write detailed documentation, tutorials, etc.
If you do want to go deeper with documentation, then you'll need a dedicated team (like a team of testers) that work exclusively on documentation. At some point it does make sense to hire only for that, and it can even be a differentiating point for your startup if done correctly.
For libraries, a ratio I've seen works pretty well is approx 1:3:5 for lines of code:tests:docs; you can do tests first, or even documentation first, but once everything is finished and if you count the amount of lines that's a decent ratio. Note that when counting "lines of docs" in an editor, a whole paragraph will count as just 1, so in reality there's a lot more docs.
Note: I'm the creator of both https://documentation.page/ and https://documentation.agency/
* (only 2 "negative" paragraphs on a book-length article)
Re: The Surprising Power of Documentation
#7Most software documentation is:
- the part of the software you didn't have the developer resources to implement
- so you decide to write documentation to have the "code" that runs on the user's brain
Re: The Surprising Power of Documentation
#8It's hard to argue with, especially if you've experienced using good documentation. OpenBSD's man pages are one example. It takes a little time to break the habit of checking Google first and instead checking the man page first (you eventually learn that you rarely need more than that). The key word is "good" documentation. That takes time and effort to write, and it takes time and effort to keep it updated as things…
another key word is "searchable" documentation, and that's where man pages fail big time leading you to the likes of Google
Re: The Surprising Power of Documentation
#9It's hard to argue with, especially if you've experienced using good documentation. OpenBSD's man pages are one example. It takes a little time to break the habit of checking Google first and instead checking the man page first (you eventually learn that you rarely need more than that). The key word is "good" documentation. That takes time and effort to write, and it takes time and effort to keep it updated as things…
> OpenBSD's man pages are one example.
OpenBDS's developer to user ratio must be less that 1 to 1000s. When you update one line of document, you're probably saving time for thousands of users accross years of use.
Most project I worked on had at most a few dozen people with an actual chance of reading the documentation, and the majority of them aren't users, they'll be reading all the code anyway because they're not in a position to blindly trust the documentaton.
Why should we calculate the ROI of the time spend on maintaining good documentation the same way in both cases ?
PS: I also think a distinction should be made between specification and documentation. It feels that both are conflated too many times.
Re: The Surprising Power of Documentation
#10We're currently trying to document an existing large Angular application and it's daunting. We wrote some meta-code to list all possible routes and attach components to routes (we were hoping Compodoc would help, but it doesn't work well anymore).
We have over 700 routes (screens), 1200+ components and 500+ different service calls that query APIs in the back end. If we only look at routes and hope to spend, on average, one day per screen, that's 700+ days of writing docs, which is a considerable amount of work.
There's no existing documentation, save for 30,000+ JIRA tickets over a 5-year period, that describe various bug fixes and change requests. But those tickets are just floating in the ether and are not formally attached to any specific component, let alone route.
I was hoping AI would help but I can't seem to find anything relevant.
What would you do?