6

How important is a documentation? or a spec for that matter?

I've been writing software professionally now for about 5 years. Each new job I start I am more often than not faced with spending a few days reading the code trying to figure out how everything works, taking notes, and eventually producing the documentation I wish I had at the start.

Some of these companies are quite well known and I've been amazed they don't have enough documentation.

Is this something anyone else is familiar with?

Improve this question
3
  • What do you put in this document you create? You would then have a more specific question(s) about why this isn't typically done. If one programmer can come out of the cold and write meaningful documentation in a few days, it seems that most projects had enough slack time for someone who was on the project to create. Nothing against you, but I'd think they could have created it in less time since they should know more about the project.
    – JeffO
    Commented Dec 8, 2016 at 22:37
  • 1
    What documentation do you leave behind as you go from one project to the next?
    – JeffO
    Commented Dec 8, 2016 at 22:38
  • The question is: is the documentation made from code or the code from a documentation? It should be the latter, but in practice it's the first. That's why documentation always sucks.
    – user188153
    Commented Dec 8, 2016 at 23:09

3 Answers 3

Reset to default
9

Everyone agrees that documentation is important.

However...

Many programmers believe that code should be "self-describing," that the code itself should act as the documentation, and that therefore you don't need documentation. But that's only true to a certain extent. Code does not adequately document the relationships between components. It's unreasonable to ask the programmer coming after you to wade through a 100,000 line code base trying to figure out what all those abstract factory factory factory objects you wrote are supposed to do.

Documentation takes time. The first priority in most companies is shipping, not documentation. When there is documentation, it often documents their business processes or provides a user guide, but not the relationships between software components.

Documentation is another thing that must be maintained. Unlike self-documenting code, documentation must be kept up to date, otherwise it will no longer agree with the code (which is the real source of truth).

For all of these reasons, documentation is often neglected.

Improve this answer
4
  • 1
    In addition to (and in my opinion, superior to) self documenting code, good tests make great documentation. They can document how components behave, how they are constructed, and their relationships with other parts of the system.
    – Angus Goldsmith
    Commented Dec 8, 2016 at 16:57
  • 1
    @AngusGoldsmith, 100% agree. The code documents what; the tests document the why/how, which is at least as important.
    – David Arno
    Commented Dec 8, 2016 at 17:19
  • 1
    That's easy to say. In the real life, the code is more likely the "The Dead sea scrolls".
    – Laiv
    Commented Dec 8, 2016 at 18:36
  • Even after reading the documentation, you'll have to read the code anyway just to make sure the code does what the documentation says.
    – Eric King
    Commented Dec 8, 2016 at 20:55
7

Up-to-date, correct and well-designed documentation is a must. However, if it doesn't fulfill those three criteria, then it's worse than useless: It's a time/disk/soul-sucking hell.

One of the problems I find in medium/large projects is that there is a fetish about documentation, but absolutely no notion of what documentation is for, namely:

  • Documentation is not a tick-box.
  • Documentation is not a Microsoft Word "document" containing mostly boilerplate screenshots of the installation/configuration wizard. (99% of the "documentation" I find (or is requested of me) is of this kind).
  • Documentation is an annotated live graph of all relations (both in-system and external flows).
  • Documentation is a live wiki that's collaboratively build by all the stakeholders of IT. Note that I didn't say project.
  • Documentation must include all the configuration options, and for each one, it must specify which value it has or exactly where and how that value can be acquired.
  • Documentation must also state why option X has value Y, and whether the decision was technical (e.g. we're using jumbo frames because it increases performance and reduces system load) or political (e.g. we're not using auto-negotiation because there were some bad experiences on 20-year-ago Version 0.0.1 cards/switches).

As much as possible, don't "document". Do a graph, document it on the wiki and load the data from a CMDB.

Improve this answer
1
  • 3
    Agreed, bad documentation can be worse than no documentation at all.
    – Robert Harvey
    Commented Dec 8, 2016 at 18:11
1

The point is the document is far more useful to you (the new guy) than the people who have been working on it for years. I've produced similar documents and even maintained them for a while; but I suspect if someone tried to pick up from me they'd face difficulties.

Improve this answer
1
  • 1
    Ideally, documents to help with a transition should be written, read by the new member(s) with the chance to ask questions, get clarification, etc. Then an update should be made to avoid misunderstandings. I try to do this when I write directions.
    – JeffO
    Commented Dec 9, 2016 at 23:58

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.