Hacker News Reader

Comment by arendtio | Hacker News Reader

Well, I think even more important than the amount and coverage of documentation is its quality.

I have been in projects, where it would have been favorable if there would have been no documentation at all because the existing one was simply wrong and it took the organization weeks until someone noticed it and got a developer to actually look into the code.

View on HN

This is one of the reasons I tend to prefer comments over external documentation whenever possible. No, there's no magic force keeping comments in sync with the code they document changes, but you at least have a fighting chance. Programmers have enough state to juggle in their head as it is without expecting them to even necessarily know what all the external documentation it is they should update. Heck, even with comments it can be bad enough knowing whether some change to this module necessitates changes to comments in other modules in the code that you may have just looked at.

It isn't always possible. Very high-level architecture may belong in a format where diagrams are more available, and the high-level design justification for the project itself doesn't have a great place in the code.

Similarly, I try to bake the documentation directly into the code. Eg (from a shell):

  OPTION(*line=='[',"[EXPR]","the result of evaluating EXPR as a math expression (see -?m)")
    { ... }
  qsh -?s | grep -F '$['
      '$[EXPR]': the result of evaluating EXPR as a math expression (see -?m)

So OPTION does triple duty as 'comments', documentation, and the actual test for what kind of substitution is being parsed. This tends to be at the mercy of code structure though.

Without context, I have no idea what are you trying to imply or document with OPTION?

I can more or less figure out what the code does, but not why it does it. Here you should document why are you grepping for something

Developers have to be hands-on with documentation. Even if tech writers produce the final copy, devs need to be willing to provide sufficient notes to explain what needs to be documented.

I've worked (as a tech writer) at places where good documentation was part of the developer culture, like RethinkDB, and at places where documentation was seen as either something to get around to later because gosh we're just so busy now or something that tech writers can just magically pull out of their (ahem) hats with no guidance. I've been at one place where the same dev lead who literally walked out of a meeting with me saying that he didn't have time to follow the guidelines I'd written up at his request later berated me for not keeping documentation up to date. You know, documenting changes that I could only learn about if his team followed the guidelines he blew off.

Not that I'm still a little salty about it.

Anyway, tl;dr:

* If you want good documentation for your thing, you need to pitch in.

* Internal documentation matters.

* For developer tools, documentation is basically your UI. Don't skimp.

Reply on news.ycombinator.com