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

141–150 of 153 posts

Re: The Surprising Power of Documentation

#141

Post by Capricorn2481 »

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.

> Do you want a 100 page install guide or a fully automated install script

Is there an example that actually happens? A system requiring 100 pages of documentation just for installing is not getting done in a single script

Re: The Surprising Power of Documentation

#142

Post by hahnbee »

Multicomp wrote: post #125
hahnbee wrote: post #45

Earlier quoted context omitted.

stale documentation is worse than no documentation

The cause of stale documentation? Not writing documentation. According to this saying, the fix to stale documentation is (often implied) to not write documentation. Can't go stale if it doesn't exist! The above saying is so often used as an excuse to write no documentation so much that while stale documentation can provide more acute pain than no documentation, the chronic pain of no documentation is a cure worse tha…

Ah I can totally see how my simple statement can imply that I would advocate for no documentation. This wasn't my intention. I think it's important to provide all team members with resources and guidance on how to maintain documentation so that it doesn't go stale. Documentation requires extra time and maintenance but providing tools to decrease the effort to ensure that written documentation doesn't go stale is important for every technical team leader to do.

Re: The Surprising Power of Documentation

#143

Post by SnoopDougDoug »

I've been creating software developer docs for decades. Most contain the following content:

About X Installing and configuring X Using X X Reference

Typically developer docs are created from the bottom up. The devs create the preliminary reference docs using special comments in their code.

Once they are through, I go through their comments and wordsmith them.

After the reference topics are written, I start adding a "guide" section. I like to call this the "How-to" section, which answers questions like: * How do I create Y * How can I ... and so on.

I try to answer two classes of questions: * Tasks that everyone does (create a client, ...) * Tasks that flummox a lot of people (talk to the folks manning the help desk)

Once I'm happy with these task-based topics, I'll create a simple "Hello world" tutorial. This topic helps the user know that they've successfully installed and configured the software.

Finally I'll write the installation and configuration section.

It's possible to work on more than one section at a time. In fact, I typically write a bunch of sample code to try out ideas before I create the guide and tutorial. If possible, I'll tidy up these code snippets and add them to the docs. Developers always ask for more code examples.

And speaking of which, if you do create a code example, please create an accompanying unit test. Don't make your users find out that version 1.1 broke your code example. That's your job.

doug in Seattle

Re: The Surprising Power of Documentation

#144

Post by SkipperCat »

crispyambulance wrote: post #94
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…

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.

I should probably elaborate. When saying simple, I meant don't add content that doesn't relate to what the user needs to use the product. There's nothing worse than having to read a several paragraphs of unrelated content just to get to the nugget of info which tells you how to actually use the product.

If the user needs complex docs to perform a complex task - that's 100% OK. Just don't write complex content when a simple (or direct) explanation will do.

Re: The Surprising Power of Documentation

#145

Post by Prashanth_R »

Documentation can play a significant role in reducing support tickets by providing users with the necessary information and guidance to resolve common issues on their own.

To identify the hot topics on support tickets, the docs team can liaise with the customer support team to get the support tickets data and figure out the content strategy. The docs team can add sections like FAQ, troubleshooting, customization, and best practices to address the queries. This can yield in reducing future support tickets.

You also need help from the support team on this task. When a customer raises a query that is already present in the docs, they should share the response along with the respective docs page link. This action would help the customers identify that the docs page is up-to-date and their queries can be resolved through self-service rather than a support ticket.

Re: The Surprising Power of Documentation

#146

Post by underdeserver »

c00lio wrote: post #65
mailund wrote: post #38

Earlier quoted context omitted.

This is one thing that has always bothered me! A lot of clients ask if I have checked the documentation when I have a very specific question. The documentation however, is just a drive of a bunch of recorded meetings with no tags or transcripts. Am I really supposed to linearly look through tens of hours of recorded meetings to see of the detail might have been mentioned on one of those?

If they are clients or people responsible for any kind of budget, just phrase it as a business offer: I can watch through the 89 hours of relevant documentation in 89 hours for $165 an hour. Pricing fixed if accepted within 2 weeks of offering date.

Well, we have Whisper now, so you can transcribe them and search.

Re: The Surprising Power of Documentation

#147

Post by syntheweave »

Cthulhu_ wrote: post #88
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…

There's another category that's missing from most of the (enterprisey) companies I've worked at; procedures. Think of the result of an event storming session; consider all the steps involved in all layers of your application when a user creates a new session, or wants to do X in your application. Ex: I work in the energy sector at the moment; because their gas/electricity usage varies across the year, there's a syste…

I hit an oddly specific realization this weekend while working on an architectural spec: I make better documentation with a color multipen.

The reason why is because it allows a diagram to support more of the cross-cutting concerns by drawing a red arrow or a green arrow through things instead of a blue one.

It's a big moment in my realizations around technical communication. Like, I already knew this stuff mattered, but it's made more concrete when you can look at a diagram and the holistic whole helps you make more sense of things even if the details aren't right yet.

Re: The Surprising Power of Documentation

#148

Post by jononomo »

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…

You've put your finger on exactly why I don't like this kind of documentation.

Also, I don't tend to trust it as much, because it isn't actually what the program executes.

When I'm trying to read the source code I don't want to read about the source code -- I want to read the actual source code -- and if I keep coming across long multi-line idiotic comments then it breaks my flow and concentration.

I like the source code itself to be extraordinarily readable, with long and descriptive variable and method names, but I want it to be dense and packed into paragraphs of sense.

To the extent there are any comments at all they should be extremely short and completely clarifying -- they should not even partially overlap with information conveyed through function or variable names, for instance.

Re: The Surprising Power of Documentation

#149

Post by jononomo »

c00lio wrote: post #47
cjfd wrote: 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…

Wouldn't it be more efficient to just read the source code? Also, the point the guy you're responding to is making is not that code shouldn't be documented, but that in-line documentation of this variety is not that great. You seem to be interpreting him to be saying that the code shouldn't be documented at all, which is not what he is saying.
Post reply on HN