Automation for the People: Pushbutton Documentation

2 Comments

1. 2008-06-19 7:46 am

   Yamin

   This is useful to some extent, but I’m wary of automation documentation for the programmer.

   I always ask myself… how would another programmer use this documentation. If it’s something they can find in the code, then what’s the point really? There is no substitute (yet?) for a good high level document that shows in general how things work, the major files…

   The details are always in the code anyways…and any documentation that can describe the code in detail will be as big as the code anyways. I’ve seen people just create useless documentation. Like copying the header file as documentation for the class… what’s the point…just refer me to that header file.

   Automation is good for some things, but it doesn’t yet replace over documentation… which btw…if you’re doing timing diagrams… should take place BEFORE you start coding.

   Edited 2008-06-19 07:47 UTC
• 2008-06-19 2:33 pm

  Doc Pain

  This is useful to some extent, but I’m wary of automation documentation for the programmer.

  I welcome every tool of automation as long as it helps me doing my job without forcing to much “work aside” just to get it running. 🙂

  There is no substitute (yet?) for a good high level document that shows in general how things work, the major files…

  That’s correct, and if you have your documentation sources in text form (for example, LaTeX source), you can still use automated mechanisms on both the documentation and your program’s source code, for example, if you need to rename or reorder something. But you need to have an eye on both components.

  The details are always in the code anyways…and any documentation that can describe the code in detail will be as big as the code anyways.

  It highly depends on the code’s quality. While some programmers use meaningful identifiers, look after tidy code, avoid strange or confusing constuctions or simply obey some of the basic rules of coding, others code like it comes out of their nose: untidy code, strange identifiers, even stupid concepts that may (!) work, but are not to be recommended. I know it, I did it myself in the early years. 🙂

  setpicardcolor(x0+x+ax(rs(r,10,12),r,a),q[qa],w[qa,ws]); /* 1. St. v. Rkt. here */

  The understanding of the need to follow some simple rules is something programmers need to learn first, and then need to practice it during their daily work. Of course, “script kiddies” will never understand it, they don’t care about documentation anyway.

  Just to name an example of excellent documentation, I’d like to point my finger at the FreeBSD operating system. The source of the OS, its kernel, utilities, and files, is very tidy, well documented within the code, and documented by a man page for every kernel interface, driver, library call, program or system file. Of course there’s much work involved to create such a good documentation, but I’m always glad I can rely on “man foo” if I need to know how something works.

  I’ve seen people just create useless documentation. Like copying the header file as documentation for the class… what’s the point…just refer me to that header file.

  Hmmm… that’s really useless. I hope it came printed with the product. 🙂

  Useless documentation is no documentation. Instead of just copying information that you already find in the source code – as you mentioned before -, good documentation should include a certain value of abstraction, or maybe examples. A piece of paper (“handbook”) with funny pictures that does not help you using the product or understanding a library’s functionalities is completely useless.

  Automation is good for some things, but it doesn’t yet replace over documentation… which btw…if you’re doing timing diagrams… should take place BEFORE you start coding.

  Oh, well said. There are developers our there who should remember this. Coding is just a small piece of development. And it finally manifests in form of money. For an introduction about the relationship between projecting, software costs and development time I suggest reading Engelien, Dr. M.: Strukturierung beim Entwurf von Software.

  in: Rechentechnik / Datenverarbeitung (rd) Nr. 5 / 1982 (19. Jg.).

  Verlag Die Wirtschaft. Berlin (DDR). 1982. S. 5 ff. — Structuring at the design of software. in: calculation technology / data processing no. 5 / 1984 (19th vol.), publisher the economy, Berlin (GDR), 1984, pp. 5 cont. — my sloppy translation, done completely manually. 🙂