Writing Documentation 583
"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?"
Out of curiousity (Score:5, Insightful)
A point about M$ word (Score:5, Insightful)
Documentation is not evil! (Score:5, Insightful)
- Do feature reqs (10%)
- Do design spec / unit spec (30%)
- Do documentation (30%)
- Write code (15%)
- 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.
Re:PEBKAC (Score:5, Insightful)
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 [lyx.org], latex2html (comes with LaTeX), and dvipdf (comes with ghostscript).
--Bob
Possible solution (Score:2, Insightful)
LaTeX seemed the simplest way (Score:5, Insightful)
Another Great Benefit of Java (Score:3, Insightful)
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.
javadoc works well for Java code (Score:2, Insightful)
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
No question - use LaTeX (Score:5, Insightful)
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 [circlemud.org], 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 [circlemud.org]. Using pdflatex (NOT ps2pdf), you can also create very high quality PDF [circlemud.org], which includes a real PDF table of contents, cross-references, and URL links. Finally, using latex2html, you can create almost native-quality HTML documentation [circlemud.org]. 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.
Not to be the obvious, but upgrade to Win2k or XP (Score:2, Insightful)
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
Re:PEBKAC (Score:2, Insightful)
...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.
Use DocBook and document as you code (Score:3, Insightful)
- it helps the planning process immensely by forcing you to really think about what your code is going to be doing, and
- 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.Re:Documentation is not evil! (Score:5, Insightful)
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.
Another vote for LaTeX here (Score:5, Insightful)
Put me down for LaTeX as well, please. In its favour (in this particular context)...
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.
Ten Reasons Why TeX/LaTeX is Better than Word (Score:5, Insightful)
Re:PEBKAC (Score:2, Insightful)
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
FrameMaker?? (Score:2, Insightful)
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.
Word is horrible (Score:5, Insightful)
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.
roff (Score:2, Insightful)
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.
Re:HTML, LaTeX, LyX., Word... (Score:2, Insightful)
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.
Re:PEBKAC (Score:2, Insightful)
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.
Re:PEBKAC (Score:3, Insightful)
I switched (Score:5, Insightful)
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).
Re:Documentation is not evil! (Score:5, Insightful)
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.
No, you're an idiot (Score:5, Insightful)
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
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.