Slashdot Mirror

← Back to Stories (view on slashdot.org)

Writing Documentation

Posted by Cliff on from the the-unglamourous-side-of-development dept.

twms2h queries: "It is everybody's favorite task, the worst part of programming: writing the documentation. I have been charged with writing lots of documents, some smaller some larger, most of them documenting programs I wrote myself. In order to avoid the torture of fighting with Microsoft Word all the time (which crashes on me regularly) I am looking for an easy way to get printed and electronic (HTML/PDF) documents from as simple a source as possible. I have looked into several of the processing tools that are available on the net." Below is twms2h's take on a few of the documenting systems available. The preference is to keep things simple, editing ASCII files to produce high quality documentation. Are there other tools some of you know of that might prove to be better solutions?

"So far, I like aft, mostly because it is simple to use, and gives me nice result as HTML. Unfortunately HTML is not enough, since I also need a very good looking printable version.

There are alternatives like DocBook, which I could not get to work and udo (Page is German, get the translation from the fish) which I have not yet looked into very closely.

Then of course there is TeX and any number of WYSIWY-won't-G word processors. I haven't used TeX much, I only tried my luck in writing a few letters (and found out that it is not suitable for this). I went through hell when I wrote larger documents with various versions of MS Word and I am not really a fan of Star Office even though version 5.2 has not yet crashed on me (however 6.0 beta did). KWord, part of KOffice doesn't seem to be stable enough yet.

I would prefer a simple ASCII only format as the source for being converted to more complex formats anyway, especially since it could be easily put into CVS for version management (Anybody tried that with MS-Word documents? Don't!)

As all these projects show I am not the first one faced with this problem. I wonder what experiences Slashdot readers have had with these and other packages?"

25 of 583 comments (clear)

  1. Out of curiousity by Sheepdot · · Score: 5, Insightful

    Just out of curiousity, what are you writing documentation for? I myself would approach the problem according to what kind of software it was, and who the intended audience was.

  2. A point about M$ word by Anonymous Coward · · Score: 5, Insightful

    It will do versioning. See the menu file/versions

  3. Documentation is not evil! by deblau · · Score: 5, Insightful
    In fact, in most projects, documentation is more important than the code itself! This rule holds for all programs you intend for someone other than yourself to run (or, heaven forbid, debug later). My general rule of thumb for doing projects is:
    1. Do feature reqs (10%)
    2. Do design spec / unit spec (30%)
    3. Do documentation (30%)
    4. Write code (15%)
    5. Beta-test / debug (15%)
    Notice that design and documentation take up more than half the time on the project. Implementing the code becomes very easy with good, fleshed-out design and documentation.

    As for solving your problem, I generally write documentation in-code using one style of comments and line-by-line comments using another style. Then forming docs from the code is easy: write a little perl script to extract the block comments, and format as you like.

    --
    This post expresses my opinion, not that of my employer. And yes, IAAL.
    1. Re:Documentation is not evil! by FortKnox · · Score: 5, Insightful

      but you write the documentation as comments to the code you haven't written yet

      ABSOLUTELY!
      You should design every object and every function (down to what the functions input and return are) before coding everything. You should be able to write comments on the function (on the function, not in. Even having stubs for the function) before it is written. Then, you know EXACTLY what the function needs to do when you code it. You even have a nice reference doc for your teammates (if you use javadoc with java).

      I've taken this approach MANY times, and I can't tell you how SIMPLE it is to code with this. Its like a homework assignment "Write a function foo, that takes two integers, adds them, and returns it as a real". The code practically writes itself. And the project manager usually doesn't have any trouble tying all the objects together.

      I might as well add that this is a great technique to make open source work well and fast.

      --
      Good quote, too many chars. Seriously, the slashdot 120 char limit sucks!
    2. Re:Documentation is not evil! by Anonymous+Brave+Guy · · Score: 5, Insightful
      You should design every object and every function (down to what the functions input and return are) before coding everything.

      Sorry, gotta disagree with that. The place of design docs is not to mandate the details, like the exact function inputs and outputs. The place of the design docs is to paint the big picture, perhaps down to assigning the responsibilities to the major building blocks of your code (principle functions, classes, etc.).

      Requirements change. This is a fact of life. No real project I've seen since I was a student had requirements that stayed fixed, or even close to fixed, during a whole development cycle. As a result, your design must change.

      Furthermore, your initial design will probably be flawed in many ways you don't anticipate until you start trying to implement it. Unless you're copying an algorithm out of a textbook or a design you've used before, you'll be lucky to be even close to your final design on your first pass. As a result, your design will evolve.

      If you attempt to record every little detail in the design docs, two things will happen. First, you will cripple the pace of development, as you spend more time updating paperwork than you spend developing. Secondly, your design docs will rapidly become out of date, and hence useless anyway.

      The correct place for comments about the details is in the code. This is where you should record the exact input/output parameters of a function, the behaviour in error cases or the meaning of a little helper function. A combination of descriptive names for things and judicious use of comments will do far more for you than a 500 page printout of last month's code base.

      Making your code its own detailed documentation allows for fast prototyping -- often the quickest way to find a good basic design -- and for ready modifications as the design evolves. This leaves design docs free to do what they should: recording the overall design.

      Welcome to the 21st century, where the waterfall model dried up.

      --
      If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
  4. Re:PEBKAC by mcelrath · · Score: 5, Insightful
    Uh, wrong.

    If an application crashes, it's the developer's fault. Period. End of story. It is NEVER the user's fault.

    To answer the article's question. I recommend LaTeX, LyX, latex2html (comes with LaTeX), and dvipdf (comes with ghostscript).

    --Bob

    --
    1^2=1; (-1)^2=1; 1^2=(-1)^2; 1=-1; 1=0.
  5. Possible solution by Fembot · · Score: 2, Insightful

    HTMLDOC appears to serve your purpouse. It appears only windows binaries are avalible however but the sourcecode is avalible under the GPL

  6. LaTeX seemed the simplest way by StormC · · Score: 5, Insightful

    I've been writing documentation for a little while now and LaTeX always seemed the best way to solve the problem. You can make nice pdf and print version. Yes it takes some time to get use to and most WYSIWYG people don't like it but it rocks in CVS.

  7. Another Great Benefit of Java by Enonu · · Score: 3, Insightful
    Javadocs are one of the best resource I have at my disposal for documenting my programs and reading the documentation of others. It's a wonder something like this wasn't in mind for every major language ever conceived. Never seen them before in action? Here's a link to the docs on Sun's website. Upper left corner is the specific package you want (like namespaces). The default view is all classes. Lower left is the classes for the current package chosen. The main frame contains the specfic documentation for that class. Everything is hyperlinked to everything else, so getting from one relevant document to another is cake.

    I believe there are other systems that implement a Javadoc like utility for other language. Do a google for "Javadoc for C++" for example and plent of links show up.

  8. javadoc works well for Java code by AirHog · · Score: 2, Insightful
    The Java Development Kit from Sun comes with the javadoc tool. It extracts comments from specific locations in your source (/** */ -style comments) and produces HTML documentation. It has a plug-in architecture for support of other output formats. Sun provides plug-ins for FrameMaker and a couple of other formats, or you can write your own.

    I have automated its use on several projects. Make a cron job that:

    • Gets a copy of the latest sources from CVS
    • Runs javadoc against the fresh sources
    Each morning you'll have up-to-date documentation.

    -Andy

  9. No question - use LaTeX by jelson · · Score: 5, Insightful

    I grappled with exactly this problem for years. I wanted something that would give me superb quality Postscript/PDF, good HTML, and at least passable ASCII text. (In 1994, it was still important to distribute ASCII documentation; not everyone had a web browser.)

    I went back and forth with all sorts of things: SGML based solutions, a few more "proprietary" utilities, etc. Finally, the latex-to-other-format conversion tools got to be good enough that I could use LaTeX as my primary format.

    My most recent documentation is for FUSD, a Linux framework for user-space devices. The original documentation source is LaTeX. Simply running LaTeX gives you DVI, which you can convert into publication quality Postscript. Using pdflatex (NOT ps2pdf), you can also create very high quality PDF, which includes a real PDF table of contents, cross-references, and URL links. Finally, using latex2html, you can create almost native-quality HTML documentation. And, if you really need ASCII, you can get a reasonable rendering by running lynx (in its ASCII-dump mode) over the HTML.

    latex2html comes with special LaTeX macros that let you specify hyperlinks inside your document. They are rendered as real hyperlinks in HTML, and footnotes in the printed versions.

  10. Not to be the obvious, but upgrade to Win2k or XP by cybrthng · · Score: 2, Insightful

    I use word, Visio, Toad (oracle), eXceed (x), Lotus Notes, Netscape, Jinitiator (11i client), and SecureCRT all day long and have no problems.

    95,98, NT 4 and 2ksp1 crashed, but i have yet to have a random crash under Win2kSP2 or XP.

    Have you looked into reasons of why our PC crashes? I'm constantly building Visio diagrams, documenting schema's, editing 500 page documents full of 20-30 meg schema diagrams and at the same time telneted into several servers, and connected to an application server running on Solaris through exceed and still running Lotus notes and whatnot..

    must be buying some sour computers man.

    Hello, i just have my laptop go into sleep mode, open it up when i get hope and pick right up (with the exception of telnet sessions).

    Why change your whole application suite for what could be an obvious hardware or application problem. My pc quit crashing on my almost 2 years ago and over the last year hasn't crashed unless *I* did something wrong. (like say Yes to a message warning me my VPN driver wasn't certified for XP, but thankfully after rebooting it rolled back to a working config very nicely).

    oh well. your loss if you can't figure out what is wrong and blame it on blue screen o'death

  11. Re:PEBKAC by pmz · · Score: 2, Insightful
    Quite simply, no two MS Windows systems behave the same. The configuration control in Windows is so poor that MS Word might work great on one computer and never work well on another. If a person likes to install a variety of software from a variety of sources...well, then, pretty much all bets are off. In general, the less sofware installed on a Windows system, the better. This isn't an argument for installing only Microsoft software; this is an argument that Microsoft produced an OS that can't be managed well.

    ...as for the article, LaTeX is always good (even for writing letters), Doxygen with C++ seems pretty good, too, but, as always, plain text is best.

    --
    Healthcare article at Kuro5hin
  12. Use DocBook and document as you code by UsonianAutomatic · · Score: 3, Insightful
    Or document even before you start coding, as someone else already mentioned; I've found that starting documentation early on accomplishes two things:
    1. it helps the planning process immensely by forcing you to really think about what your code is going to be doing, and
    2. it ensures that the documentation end of the project doesn't get short shrift; once the code is done it's too easy to gloss over the documentation when the next project is breathing down your neck.
    DocBook easy to author with... the pain in the neck part is setting up a processing environment with Jade/OpenJade/DSSSL, but it's well worth it. It's also possible to use XSL/XSLT to process DocBook XML, but I don't know how involved the setup is. YMMV.
  13. Another vote for LaTeX here by Anonymous+Brave+Guy · · Score: 5, Insightful

    Put me down for LaTeX as well, please. In its favour (in this particular context)...

    1. It takes input in a text format. Use CVS, your favourite editor, etc.
    2. It also produces excellent quality output, and generating HTML, PostScript and PDF output are all straightforward with standard tools.
    3. It can generate things like cross-references, tables of contents and citations very easily.
    4. There are good packages available for free that can typeset code right out of the source file.
    5. There are freely available and very powerful diagramming tools that plug right in. (Anyone know of a speciality UML drawing package, BTW? The usual tools are OK, but I've never found, say, some Metapost macros to make it completely trivial the way it could be. Surely someone must have written some!)
    6. The maths typesetting is all there if you need it, of course. That's very useful if you're working on a scientific app and need to document the algorithms as part of the design, and it doesn't get in the way if you don't need it.
    7. It's available for minimal money and effort.
    8. It's highly extensible. If you need to do something that doesn't come as standard, you almost certainly can (and someone else almost certainly already has, and put it on CTAN for you).

    The only downside I can think of is the learning curve. Basic LaTeX use is fine, but for really good output, you're going to want your own class file and/or packages. That's fantastic once you've got it -- all your docs follow a consistent style, and you can make it easy for newbies to learn the tool. Someone has to be pretty sharp to write the class/packages in the first place, though, or you have to be prepared to buy in expert help for a couple of days.

    --
    If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
  14. Ten Reasons Why TeX/LaTeX is Better than Word by klund · · Score: 5, Insightful
    1. LaTeX math mode is a thing of beauty. Equations come out looking correct. Mathematical expressions in Word are treated as an afterthought. Equation editor is evil.
    2. TeX is guaranteed to be bug free. The author, Stanford Professor Donald Knuth, will send you a reward check is you find a bug. The reward is currently $327.68 (that is, 2^15 cents).
    3. TeX is free (as in beer) and free (as in speech).
    4. TeX has real comments. Anyone who doesn't comment their code is an ass.
    5. TeX provides a full, turing-complete, language. The text produced by your input file can be the result of conditionals (which I use to reuse sections in different documents) or the result of complicated calculations. In the TeXbook, Knuth demonstrates the power of the TeX language by defining the \primes{n} command, which calculates and print the first n primes (see page 218).
    6. There are no LaTeX "macro" viruses. You can safely receive LaTeX documents by email and not worry about it reading your OutLook address book and mailing copies of itself to all your friends.
    7. LaTeX has no GUID (Globally Unique Identifier). Word documents are embedded with a code than can be traced back to your computer (the police captued the author of the Melissa virus by tracing his GUID). Big brother Bill is watching!
    8. LaTeX versions are not incompatible. The file format has never changed. I have LaTeX files from 1989 that work without problem in the latest version of LaTeX.
    9. There is no undo feature in TeX. This is a good thing. No one can ever seen earlier versions of your TeX document by pressing the Undo button.
    10. LaTeX documents are small and lean. What's the smallest Word file on your computer?
    --
    My word processor was written by Stanford Professor Donald Knuth. Who wrote yours?
  15. Re:PEBKAC by mcelrath · · Score: 2, Insightful
    Hardware issues?

    It's a word processor, not a hardware driver. Unless ALL your apps are crashing, it's the software developer's fault.

    Misconfigurations?

    Again, the developers fault. The application should perform predictably and not crash for all possible combinations of configuration. You cannot possibly prescribe or predict what users will do with your application that you might not have anticipated.

    If it was a linux program, would you say the same thing?

    Absolutely.

    --Bob

    --
    1^2=1; (-1)^2=1; 1^2=(-1)^2; 1=-1; 1=0.
  16. FrameMaker?? by Belly+of+the+Beast · · Score: 2, Insightful

    I used to use FrameMaker until Adobe started busting engineers for making speaches. I last built an 800 page spec with FrameMaker that included timing diagrams, drawings, etc.
    Forget Word. Even with just the ASCII txt from the above document in outline above crashed it every time. FrameMaker was rock solid for the whole project with multiple authors, but I will never use allow it to be used here again after what they did to Sklyarov. Too bad, it did perform well.
    Evolve or go extinct Adobe.

  17. Word is horrible by coyote-san · · Score: 5, Insightful

    MS Word is about the worst tool around for writers.

    The problem is that it forces, FORCES, you to deal with presentation issues at all times. When I'm writing, I want to focus on the content. How is the material broken down into major sections, into chapters, into topics? What information needs to be presented before a new topic will make sense? What topics will be treated as reference material, needing easy lookup?

    This is hard enough to do with regular interruptions, but with text it's possible. I write an outline, DocBookify it, then write straight text within it while using minimal tags. When I'm happy with the content, I work on presentation (and usually loop between them a few times.)

    But Word is so damn helpful that I'm constantly interrupted. I mispelled a wrod or two, gotta fix it NOW. Esp. with the increasingly intrusive "autocorrection" that insists on "fixing" things. (And don't get me started on it's ideas of what a properly formed URL looks like, never mind the RFCs.) There's the issues around the Redmondian English. My grammar isn't perfect, but highly technical material often requires extremely complex sentences to adequately convey the nuances. Green lines are another distraction. Then there's the whole issue of lists, tables, indentations, etc. sucking your attention because you're forced to deal with presentation before you're entirely sure what's going into them. (Two tables or three? What drives columns, what drives rows?)

    Is it any wonder I, and many other people, find Word documents to be unusually vacuous? Not every text document in a Jon Postel RFC, of course, but there seems to be a direct correlation between the meat in a document and its original format. Straight text seem to be written to HS or college level, Word documents seem to be written to Jr High level at most. The problem is the polish - Word documents often strike me as first or second drafts, not finished documents. But they sure are pretty.

    --
    For every complex problem there is an answer that is clear, simple, and wrong. -- H L Mencken
  18. roff by PotatoMan · · Score: 2, Insightful
    For most documentation, I like either texinfo or *roff. Both will convert to either HTML or Postscript. Texinfo gives you Info docs as well, and does a better HTML conversion.


    For simpler documents, roff works just fine. And it follows the Unix philosophy, so you get pic, tbl, and eqn for special-purpose formatting.


    Our internal docs needed to use Framemaker (in order to be compatible with a vendor tool), and we had a program to take a simple mark-up and turn it into MIF. I replaced this with a groff to HTML and Postscript system. The HTML pages had a 'print' link that would load the Postscript and give the user a nice looking document.


    Most of this stuff is a matter of taste.

  19. Re:HTML, LaTeX, LyX., Word... by hereticmessiah · · Score: 2, Insightful
    If you had problems with LyX, it's because you were treating it as a Word Processor, which it isn't. If it's counterintuitive, that's why. this comment explains things better than I could. The worst thing about LyX is that XForms is ugly and clunky, but you get over that.

    Did you even think of reading the manuals? If I was using a program that uses a paradigm I wasn't used to, I'd read the manual. I mean, you wouldn't expect a functional language like O'Caml to work the same way as an imperitive language like C, would you? It's the same sort of thing, in a way.

    --
    I don't like trolls and mod against me if you like, but I'd prefer if you'd reply.
  20. Re:PEBKAC by Remote · · Score: 2, Insightful

    Yeah. Considering the prefect program is yet to be written, then there will always be some poor code somewhere.

    Ive been using MS-Word for years too, many versions, on anything since MS-DOS4 to W2K. There are things I dont like in Word, but stable it is.

    For example, my home machine runs Windows like a charm, but if I run Linux/XFree86/KDE/Mozilla and load a page with a few large jpgs (which IE would just eat) it begins to swap and stop responding to *any* imput except for the power CHORD! Once I just let it spin to see how long it would take. AFter 2h40min I gave up. I am sooo obviously doing something wrong, I just cant figure out what it is. So dont tell way0utwest to shut up, hes tryin gto help and giving sound advice.

  21. Re:PEBKAC by mark_lybarger · · Score: 3, Insightful

    yes, if your application needs (or can) work with a specific hardware which requires a specific configuration, then your application should take responsibility to ensure that environment is present. aborts are bad! they should not be tolerated. an application should not allow a dumb user or dumb hardware to crash it.

  22. I switched by fireboy1919 · · Score: 5, Insightful

    I wrote a publication (16 pages, IEEE format) for Word and it was a REAL pain. Word stored the whole document in memory, which actually meant that part of it was cached to hard drive. I work in the Field of Computer Vision, so I necessarily had about 10 megs of images in there. Occasionally, that would be too much for the operating system, and I'd have to wait 15 minutes or so for the memory manager to catch and resolve some thrashing issues.

    Also, every time I changed anything at all, Word would move around the pictures and mess everything up - even though I had all the pictures positioned as "absolute." At the end of the publication, any 3 minute change at the beginning of the document took half an hour to fix.
    For the next publication, I did everything in Latex. The added bonus there was that format is separate from content, and the format descriptors where already written by IEEE (and by my school for my thesis).

    --
    Mod me down and I will become more powerful than you can possibly imagine!
  23. No, you're an idiot by RebornData · · Score: 5, Insightful

    I use Word almost every day, and while many of your comments are true for default behavior, you clearly have not attempted to actually learn the program. To take the issues in the order you cite them:

    1. Word actually doesn't force you to deal with presentation issues at all times. Are you familiar with outline mode? I usually do my first drafts in outline mode, which allows you to focus entirely on content and structure independent of formatting. Outline mode works with styles to specify formatting globally for a given level in the outline. So if the top level in your outline applies to chapters, you can easily define a chapter heading style that will be automatically applied to all the top-level items. It really works well.

    2. It's been said already, but it's worth repeating: Real-time spelling and grammar correction are really easy to turn off. Really easy.

    3. Lists & indentations. You should learn how to use styles. This is exactly what they are for. For example, my default template has a "bullet list" style. If I want something to be a bullet list, I apply this style to it. The "tags" aren't visible, but they effectively are there. If I ever decide that a bullet list needs to be indented differently, or have square instead of round bullets, I can make the change once for the style. Once you've set up your default doc template with a reasonable set of styles, you never have to worry about presentation during early stages.

    4. I don't understand what you say about tables.

    5. "Word documents seem to be written to Jr. High level at most"? What the hell? This is broad generalization at it's worst. I bet more doctoral dissertations are written in Word than anything else. Although I did get a good laugh thinking about what the average grade level of a /. post would be...

    Now, I'm not saying Word is the end-all be-all. I'm just saying that you're an idiot because of the 10000 things wrong with it, you've picked issues that are almost univerally untrue, and simply reflect that you haven't learned to use it.