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

131–140 of 153 posts

Re: The Surprising Power of Documentation

#131

Post by w10-1 »

Documentation is controversial because

(a) it's an ambiguous material (like wood), so anecdata go all ways

(b) it's for the future, i.e., easy to cut in a time pinch

(c) it presumes knowledge is shared, though it's often hoarded

(d) it's a tax on everyone's time

A helpful discussion of documentation would focus on specific use-cases: on-boarding developers, backgrounding design discussions, operational run-books...

In that context

(a) The cost/benefit is concrete

(b) You've identified the consumer/stakeholder, so they can speak the the present value

(c) Present work is value in terms of that future product

Then some documentation strategies become clear:

(1) Write for some specific reader. It's not a brain dump (unless it is, e.g., for departing engineer).

(2) Build in feedback cycles with actual users before completion

(3) Make it someone's job (put them on the hook) to deliver good documentation (for all users). They can optimize extraction and repurposing across the organization.

If I see director+ level people with no strategies for documentation, I conclude they're not building an organization.

Re: The Surprising Power of Documentation

#132

Post by jrumbut »

NiklasBegley wrote: post #128
SkipperCat wrote: post #81

I can't stress this enough. Know your audience and tailor your documentation to them. You should write three types of documentation. One for users, one for admins and one about architecture. User docs are simple. How do I use it. What are the API calls, etc. Admin docs are about how to install/break-fix/troubleshoot issues that are beyond user interaction. Architecture is how the system is constructed, why certain te…

Agreed on a lot of this, but I'd be cautious about saying that any kind of documentation is "simple". Especially when it comes to technical products - be they internal or external. Technical writers train specifically to communicate complex technical topics to readers, and it's not an easy job. It requires understanding your readers, what kind of backgrounds they have, and what are they trying to achieve. This become…

> disconnected from the engineering cycle

Great phrase!

To me, there are three places that dev-generated documentation can live:

1. The code

2. The issue tracker

3. The version control system

A small amount of exceptionally useful and frequently referred to documentation like the process for setting up a new dev environment or some complex support task can live elsewhere.

Otherwise, I think the top down imposition of a documentation culture is unlikely to succeed.

The real secret to getting a team that has a shared understanding of the system, the business, and each other is to retain your developers. A team that's been together for five years has superpowers no amount of documentation can replicate.

Re: The Surprising Power of Documentation

#133

Post by manicennui »

In my experience, the only people who benefit from good documentation are the highly competent. The corporate slugs who need Stack Overflow and GitHub Copilot to accomplish anything are still going to bother others every single day. At best you can point them to the documentation when this happens, but if their problem differs even slightly from what is documented, they will need additional hand holding. They also love to use the lack of documentation as an excuse for why they can't get things done, but then expect others to figure things out without documentation for them. If you write documentation, they still won't read it and will remain helpless.

Re: The Surprising Power of Documentation

#134

Post by manicennui »

atoav wrote: post #31
franciscop wrote: post #6

This 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,…

I really like the way documentation works in Rust: You basically write markdown in a special type of comment over the module, function, datatype or method you wanna document and then you can convert that into documentation automatically. Even better: if you have examples in code blocks in these docstrings per default they get tested as well, so if you don't update them, the tests will fail and you will notice. In my…

Most popular languages have a version of this, including Java. This is only one level of documentation, and one must know a bit about what they don't know to use it effectively. In other words, if you already know that you need to use the foo function, then the foo function's documentation is great. If you don't even know which function or class/module to use, it isn't a great starting point.

Re: The Surprising Power of Documentation

#135

Post by dimal »

entropyie wrote: post #100

I'm going to go out on a limb here and say that startups should be investing spare cycles in automation moreso than documentation. Do you want a 100 page install guide or a fully automated install script? Which one is more likely to be kept up to date? Which one is more likelybto have people notice it's out of date and fix it? Documentation is helpful, but automation is a force multiplier.

Having just experienced a startup that attempted to do what you suggest, I will say that in this case, it did not work. First of all, there is so much more institutional knowledge to document than just installing something. Second of all, the first step in automating something complex is to document what it is to document.

If there is no documentation for the system architecture or how to solve common problems, everyone on the team wastes cycles solving problems that others already have, and doing it in different ways, so the codebase becomes an inconsistent pile.

Documentation is truly a force multiplier. It allows an entire team to learn from the experience of a single person, and that person can help the others passively and asynchronously.

Re: The Surprising Power of Documentation

#136

Post by marcosdumay »

cjfd wrote: post #39
atoav wrote: post #31

Earlier quoted context omitted.

I really like the way documentation works in Rust: You basically write markdown in a special type of comment over the module, function, datatype or method you wanna document and then you can convert that into documentation automatically. Even better: if you have examples in code blocks in these docstrings per default they get tested as well, so if you don't update them, the tests will fail and you will notice. In my…

I don't have experience with this in Rust but have come to passionately hate this kind of documentation in other language. I think all of pydoc, javadoc and, doxygen are all garbage. If one could apply them sensibly it would not be so much of a problem but then you have documentation nazis who force you to document every method and every parameter. This leads to hightly enlightening prose documentation that the get_h…

I am firmly on the opinion that every bit of public interface should get a documentation string.

You say "gets the height" is trivial, but that text tells not only what the function does, but also that the author couldn't think of anything else important to say. This is very different from no text at all, where you can't be certain if the author even thought about it.

IMO, enforcing an internal structure (AKA "you must document each parameter and the return value") is counter-productive, but enforcing the existence of the comment is very productive.

> Also it clutters the code with many highly trivial remarks.

I'd say that it "clutters" the code with markers for public elements and hard to understand ones. Those are actually valuable, and not clutter at all.

Anyway, if those markers are a large share of your lines, you may need to rethink your architecture. It's usually not valuable to have a lot of interface for trivial things.

Re: The Surprising Power of Documentation

#137

Post by remoquete »

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…

You also need technical writers.

Re: The Surprising Power of Documentation

#138

Post by marcosdumay »

Multicomp wrote: post #123
entropyie wrote: post #100

I'm going to go out on a limb here and say that startups should be investing spare cycles in automation moreso than documentation. Do you want a 100 page install guide or a fully automated install script? Which one is more likely to be kept up to date? Which one is more likelybto have people notice it's out of date and fix it? Documentation is helpful, but automation is a force multiplier.

I write automation constantly as my full time job. Documentation of how to do processes manually is definitely ripe to be automated. But what parameters are available for the automation? Where does the automation live? How do you diagnose and improve when the automation breaks? Why did we even make this automation in the first place? These sorts of questions are ripe for documentation. Most How style questions can be…

> But what parameters are available for the automation?

A case of non-automatic automation :)

Actually, there's nothing wrong with that. Many things are best left that way. It's just an interesting oxymoron. And it's also interesting the fact that yours (and I'm sure many other's) mind jumped directly into it.

Automatic automations also exist. And those require a complete different set of documents.

But anyway, they are important because the "how do they work", "how do we fix (or improve) it", and "what can they do" are trivial to deduce from a working artifact. Those are not questions you usually want to answer with text.

Re: The Surprising Power of Documentation

#139

Post by remoquete »

I think the most important message of this blog post is this:

“ Designating a dedicated team or individual for documentation in an early-stage startup can seem extravagant. But trust me, it’s one of the smartest investments you can make. Why? Because knowledge is the lifeblood of your startup, and a dedicated handbook team acts as the circulatory system, ensuring that this vital knowledge flows freely and efficiently throughout the organization.”

So many startups lack technical writers, let alone docs teams. Not even OpenAI has one, as far as I know.

Post reply on HN