Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Surprising Power of Documentation

vadimkravcenko.com

Post reply on HN
Print view View original

11–20 of 153 posts

Re: The Surprising Power of Documentation

#11

Post by sarnowski »

eviks wrote: post #8
SoftTalker wrote: post #2

It'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

What degree of „searchable“ are you missing from apropos?

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

Re: The Surprising Power of Documentation

#12

Post by diarrhea »

gervwyk wrote: post #5
gervwyk wrote: post #4

100% 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…

I wish reading docs more or less fully was more normalised. Time and again I find myself suddenly the, or close to the subject matter expert just because I actually read the documentation of what everyone else had already been working with for years, but was new to me. I don’t consider knowing a technology or tool without that step.

As you said, without it, you’re in the dark, doing guesswork. Doing that with multiple people, like a call with everyone guessing, is even worse. Just have everyone read the docs on their own time. So valuable.

Re: The Surprising Power of Documentation

#14

Post by onion2k »

bambax wrote: post #10

We'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 averag…

What would you do?

Accept that it's a big job and just get on with it. Sometimes we just have to do hard things. Putting it off or looking for a shortcut doesn't always work.

I'd also spend a couple of months seeing how much of the documentation production I can automate though. That's a small investment in a 700 day project.

Re: The Surprising Power of Documentation

#15

Post by bad_username »

bambax wrote: post #10

We'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 averag…

I would go from the most pressing problem, apply the Pareto principle to solve it, and repeat until reasonably happy. What is the biggest actual pain that the current lack of docs causes? I do not yet know the answer (feel free to share), but there is a good chance that the problem does not actually require a formal description of every screen one by one. You may be trying to create reference docs where higher level and more abstract documentation is warranted.

Re: The Surprising Power of Documentation

#16

Post by Klaster_1 »

bambax wrote: post #10

We'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 averag…

As a fellow Angular developer at a similar state of affairs, I am curious as to what problems you think documentation would solve, how you plan to maintain it after more "Jira tickets" layer up and what's your general strategy.

Re: The Surprising Power of Documentation

#17

Post by beachy »

bruce511 wrote: post #3
SoftTalker wrote: post #2

It'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…

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

#18

Post by r_hoods_ghost »

bambax wrote: post #10

We'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 averag…

Hire a couple of technical writers with experience and let them get on with it, and then make your devs document every new feature and change. Nothing passes code review unless it is accompanied by updated documentation. Getting your devs to document the existing codebase when you've inherited a shitshow like this will pull them away from their jobs for too long.

Re: The Surprising Power of Documentation

#19

Post by 63 »

I'll add that what a lot of non-developers seem to think is documentation is not actually worth very much. For instance, a 2 hour recording of a zoom meeting tagged only with a date and general topic is worth so much less than a searchable text guide on the same topic. Recording a meeting is not documentation! Especially if it's not tagged properly and made available to the people who need it. It's also impossible to update a meeting recording of course so it's guaranteed to be out of date after enough time passes, requiring that meeting to be held and recorded again.

Other things that I see treated as documentation when they're not: slack messages, uncommented code ("self-documenting" code exists, but it's much rarer than management seems to insist), vague jira tickets, some guy who worked on the app 5 years ago and is happy to answer questions even though he's in a new role now, etc.

Re: The Surprising Power of Documentation

#20

Post by pacaro »

bruce511 wrote: post #3
SoftTalker wrote: post #2

It'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…

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.

Post reply on HN