News for hackers. Stuff that matters.
Re:The Surprising Power of Documentation by SoftTalker on Monday June 12, 2023 @12:10AM (#36288356)
It's hard to argue with, especially if you've experienced using good documentation. OpenBSD's man pages are one example. It takes a ittle 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 ffort 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 by bruce511 on Monday June 12, 2023 @12:54AM (#36288602)
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 by abraae on Monday June 12, 2023 @02:51AM (#36289331)
Certainly writing is a skill that many programmers are not good at.

However IMO an easy trap to fall into is to start documenting without a bigger understanding of the audience and the purpose of the doc.

A good way to start is to identify which of the 4 types of documentation you are working on.

https://nick.groenen.me/posts/the-4-types-of-technical-docum...

Personally I find it very easy to put too much explanation in the wrong places.

Re:The Surprising Power of Documentation by pacaro on Monday June 12, 2023 @03:11AM (#36289506)
This issue around poor writing skills is something that I've thought/worried about for a while. At some level of seniority (the more junior the better IMO) we expect developers to write design docs. The inability to communicate clearly in those documents is a huge problem. Oftentimes misunderstandings and ambiguities are cleared up at design review, but then never reintegrated into the document, leaving two artifacts, the implementation and the design doc. These obviously drift over time, maintaining correspondence is hard. But when one only ambiguously described the other from the get go, then the documentation is broken. This too is technical debt.

If you are fortunate, you can write code in an organization which has a high code quality bar, uses consistent styles etc. But it is rare (vanishingly so I nearly 30 years experience) to find the same bar applied to the design docs.

Re:The Surprising Power of Documentation by remoquete on Monday June 12, 2023 @01:23PM (#36297294)
You also need technical writers.
Re:The Surprising Power of Documentation by eviks on Monday June 12, 2023 @01:31AM (#36288810)
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 by sarnowski on Monday June 12, 2023 @01:58AM (#36288973)
What degree of „searchable“ are you missing from apropos?

https://man.openbsd.org/apropos.1

Re:The Surprising Power of Documentation by eviks on Monday June 12, 2023 @03:52AM (#36289850)
All of the basics of anything google-like: typo-friendliness with word forms and phrases, links to source, formatting of output, GUI, or not spamming the output with a dozen of lines of warnings that some man page files are missing.

Then a bunch more degrees that I could know about if the tool were more usable

Re:The Surprising Power of Documentation by BLanen on Monday June 12, 2023 @08:55AM (#36292658)
Yes.

I mostly use man pages when I already basically know the program and need to do specific thing.

Even then I don't use man itself but usually a webpage of the manfile because of UX.

Re:The Surprising Power of Documentation by makeitdouble on Monday June 12, 2023 @01:46AM (#36288894)
> 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 by allknowingfrog on Monday June 12, 2023 @09:37AM (#36293215)
ROI should always be a consideration. It's reasonable to argue the merits of documentation. It may even be reasonable to argue that most projects would benefit from increased documentation. Without knowing how long it will take to write it and how many people will use it, you cannot reasonably insist that writing more documentation should be a priority for every project.

Much like automation, the question should be phrased in terms of how long it will take and how much time it will save. https://xkcd.com/1205/

Re:The Surprising Power of Documentation by euroderf on Monday June 12, 2023 @06:22AM (#36291161)
Agreed on your last paragraph. One of my mantras to coders, as a tech documentarian, was that "Incorrect documentation is worse than no documentation".