Live data from Hacker News

The Surprising Power of Documentation

vadimkravcenko.com

101–110 of 153 posts

Re: The Surprising Power of Documentation

#101
post #99

Earlier quoted context omitted.

> You should write three types of documentation. One for users, one for admins and one about architecture. I use an airplane analogy (different order than your three above): 1. "Congratulations on purchasing your 747" 2. "This is how you replace the auxiliary power unit" 3. "This is how you survive the engine catching fire"

1 is not documenting anything, and both 1 and 3 are meant for pilots? Who are the "users" in this analogy?

"1" is for the airline. What does purchasing the plane, or a fleet of such planes, mean to the company? What will be the benefits, duties, obligations wrt to the airplanes, at a high level?

Edit: word choice

Re: The Surprising Power of Documentation

#102
post #47
post #39

Earlier quoted context omitted.

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 a documentation nazi. I hate it when people skip over documentation because something is obvious or trivial to them. Stuff isn't obvious or trivial to people who have to use your code. get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects? Is it a stable and reliable part of the API or bound to change soon? Is it thread safe? Will it ch…

> get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects?

In my experience, if your documentation covers all these aspects it's guaranteed to be either wrong, misleading, or out of date on any of these details, and you better read the actual code to be sure.

In particular, the answer will often be "it depends on what the rest of the system does". Perhaps it delegates the actual calculation to an API, and this doc won't change when the API changes in a _mostly_ compatible way.

I mean, even with the best efforts given, code has bugs, words are vague, there's no way you should trust the dev who wrote the code to properly convey what it actually does.

Re: The Surprising Power of Documentation

#103

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…

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

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

#104

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.

It’s not just startups. I’ve been working in “The Enterprise” for 28 years and with one or two exceptions, my time would have been better spent automating internal processes that were documented than working on the actual product. And by better spent I mean the money saved in person hours manually and many times errantly repeating tasks that could have been done by software, exceeded any revenue generated from the product software I was working on.

Re: The Surprising Power of Documentation

#105

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.

Excellent point. Even as a non developer we are automating things like deploying databases for a application and complete system backups. We pay for that app to be developed but it pays off 200x once it's deployed and realized across all the like systems we manage.

Re: The Surprising Power of Documentation

#106

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…

Reminds me of the four types of documentation that sometimes get listed: tutorials, how-to guides, technical reference and explanation. (Usual caveat of all models are wrong but some are useful.) https://documentation.divio.com/ My (perhaps overly simplistic) take would be that we should take the thinking we use on the product itself (Who's going to use it? In what context? What would they already know? And so on), a…

I strongly back the Divio system for documentation, it works great. But you should know that the creator of the system doesn't work at Divio anymore and the newest iteration is now called Diataxis https://diataxis.fr/

Re: The Surprising Power of Documentation

#107
The thing that seems to come out of all these conversations is to treat documentation as UI/UX.

Maybe the problem is that it is treated as a secondary activity for developers, when it should be treated as a primary activity for writers.

We don't expect developers to be good at graphic design and even UI/UX design. In fact we should expect them to be terrible at it. A developer looks at the product from the inside, he sees classes, databases schemas, etc... not the way an end user will look at it. It means he will be biased into having a UI match the code structure and not the user workflow. There is a reason UI/UX designer is a job title, it is not a secondary activity for coders. Some can do both, but it is a different job.

Documentation could be treated the same way. Have people specialized in writing documentation. People who are actually good writers. I have seen it happen occasionally, and let me tell you, when you put a good writer (coding skills optional) in charge of writing documentation, the difference is night and day. Just as how better your UI will be when done by a good UI designer, and by a good UI designer, I mean someone who actually designs for usability, not someone who just tries to make something that looks cool for sales presentation, as it is too often the case for consumer apps today.

Re: The Surprising Power of Documentation

#108
post #47
post #39

Earlier quoted context omitted.

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 a documentation nazi. I hate it when people skip over documentation because something is obvious or trivial to them. Stuff isn't obvious or trivial to people who have to use your code. get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects? Is it a stable and reliable part of the API or bound to change soon? Is it thread safe? Will it ch…

I don't agree with this answer. I fully agree that documentation is important, needs to be correct and maintained. However, I do stand by the original poster saying that it is often a bad idea to enfroce javadoc style comments to autogenerate documentation. This often leads to low quality documentation.

Like you say, get_height is a trivial function, but still requires attention. Enforcing in-code docs is not going to help to have higher quality docs, quite the contrary. You often get low effort stuff, just to make the code checker happy.

And if you put in a peer review process to validate the in-code comment, it loses all power because you might as well use that step for decent documentation. get_height should be documented in a logical place, where it makes sense indeed, like grouped with get_width. But now you have the logical place to put your documentation, and the forced javadoc comment. That's double work, and one of them will be bad quality as a result of it.

Nobody is arguing for no documentation, but I am arguing for avoiding javadoc enforcements. My solution is much simpler: have a documentation check as part of the peer review process. Sure, have a template for the documentation, but don't make it strict. Ours is simple: all juniors are on documentation peer review as part of their onboarding. If they don't get it, it needs to be fixed.

Our peer review process is quite simple: is the documentation adapted, is there a relevant unit test (we actually have low UT coverage, we only do them for critical code and as part of bug fixing, so enforced frameworks make no sense for us), and naturally is the code quality itself ok

But many companies don't do those, yeah well thats how you get shit.

Re: The Surprising Power of Documentation

#109

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…

I agree with everything you said, especially tailoring documentation for intended purpose. Except... > User docs are simple. User docs are NOT simple. You have to put yourself into the mind of someone who is going to use your software to solve a problem which they have. That's never easy and it gets really hard, really fast, as the software grows in complexity or as your audience gets wider.

To continue this line of thinking: for documents to be useful in helping a customer solve a problem the documents must answer the question 'why would I want to do X.'

A complete reference of how to do A, ..., X, Y, and Z but lacking conceptual context could actually be detrimental to a customer's productivity and the ultimate success of your product.

Providing accessible conceptual guidance can be very challenging depending on the domain.

Re: The Surprising Power of Documentation

#110

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…

[deleted]
Post reply on HN