Slashdot Log In
Writing Documentation
from the the-unglamourous-side-of-development dept.
"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?"
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
TeX gone? Nope. (Score:4, Interesting)
METAFONT is pretty much integrated into TeX if you're using... well, I've only used teTeX and MiKTeX, but there are scripts to autogenerate any fonts that are needed.
And... well, you can't compete with the userbase. It's been a standard for nearly twenty years. The original program is probably as close to bug-free as any large piece of software can possibly be. Did I mention the enormous userbase?
TeX is far from dead. It's Knuth's dream that a TeX file written today will be compilable and readable in a hundred years. Given how entrenched the system is, I think this is quite likely.
-grendel drago
Re:PEBKAC (Score:5)
A car crash isn't the same as an application crash, sorry.
Almost all application crashes are the developers fault. Only a very tiny percentage (< 0.001%) of application crashes are ever the users fault. Some of them may happen because the hardware or OS is buggy. But, that's not the user's fault. If the user goes into the registry and totally mucks it up, it still isn't the users fault. Even under Linux. If the user unplugs cards randomly from a non-hotswap PCI bus, that's the users fault. If the user breaks their system in some physical way, it's their fault. It is not ever acceptable behavior for a program to crash in the absence of a physical problem with the computer.
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).
Out of curiousity (Score:5, Insightful)
A point about M$ word (Score:5, Insightful)
try YODL (Score:5, Informative)
http://www.xs4all.nl/~jantien/yodl/ [xs4all.nl]
LYX (Score:5, Informative)
Check out doxygen (Score:5, Informative)
For a real-world example... (Score:5, Informative)
We're using Doxygen to generate HTML and man pages (!) for libstdc++-v3 [gnu.org], the standard C++ library that comes with g++ 3.x. Doxygen can also generate LaTeX, RTF/Word, and some other formats which I don't remember. If you have some additional nifty utilities installed, and tell Doxygen where they are, then Doxygen can automatically use them. Take a look at the inheritence and collaboration graphs on the pages I linked to: normally they're much plainer, and not color-coded. But I had dot(1) installed, which can generate pretty graphs.
Incidentally, LaTeX is much better than TeX when doing letters. There's a set of macros specifically for writing letters, and I use them all the time for, say, business letters.
.I'm told that it's not that hard to write a module for Doxygen to teach it how to create a new output format, if the half-dozen it knows about don't fit your needs.
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: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.
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.
texinfo (Score:3, Interesting)
through the emacs formatter and use the formatted ascii output.
So, it's old and limited but still my favorite.
Doxygen (Score:3, Informative)
dan.
JavaDoc? (Score:5, Informative)
And I don't think "documenting" is the worst part of programming. Its very sterotypical.
I love design, and document while coding (usually in Java with Javadoc comments). Isn't that the way you are supposed to code?
Especially in a team environment (even more "especially" with Open Source), documentation is critical. Having a good design documented well is how developers should interact with one another.
Also check TogetherSoft. They have software that creates the UML while you code.
I also like Together's identification of titles. A "Developer" is someone that designs, codes, and documents. A "Coder" is someone that codes. Which are you?
Docbook, docbook, docbook. (Score:5, Informative)
Still, I love the format; it's clear, it's precise, and it's very well-suited to documentation.
BTW, I'd like to point out that, if you think documentation is the worst part of programming, you're probably not writing very good documentation. Documentation can be a lot of fun. Think of it as a way to make sure that you won't have to do the maintenance later, because anyone will be able to do it based on your writing.
Re:Docbook, docbook, docbook. (Score:4, Informative)
I finally found Morphon's XML Editor [morphon.com] and have been quite happy with it for editing DocBook documents (despite the fact that it's currently a beta version that will crash once in a while).
Re:Docbook, docbook, docbook. (Score:4, Informative)
It's a bit of a pain to set up, but once it's going, it's great (much like most of Linux, I find
My only complaint about docbook is that it (currently) doesn't do math too well -- I use Walsh's stylesheets, and they don't seem to grok MathML yet -- so I have to stick with LaTeX for some things still. Oh, and its table support doesn't seem to be complete when using the TeX backend, so things may come out in unexpected ways.
LaTeX seemed the simplest way (Score:5, Insightful)
Re:LaTeX seemed the simplest way (Score:5, Informative)
In addition to producing HTML and PDF with latex2html and pdflatex, there are some other features in TeX/LaTeX that appeal to code monkeys like me.
1. Real include files. For example, you can write a mission statement page that gets included in the front of all your documents. When the mission statement changes, you only have to update it in one place, and all your documents reflect the change.
2. \ifthenelse{}{}{} conditionals. This is really handy when combined with the include files above. I have one set of source files that produce three completely different (but related) documents based on a few \def statements. For example, one's for internal use only and one's for wide release, but I only have to fix typos once.
3. Define (\def) statements. I keep version numbers and product names here. PHB says "We just changed the product name from "iCrap" to "eCrap". No problem. It's even easier than search-and-replace.
4. Comments. I comment the source files the my LaTeX documents. Most the time it's just snide remarks, but sometimes I leave useful comments behind.
%% The behavior described in the next paragraph
%% used to be a bug. Now we charge extra for it.
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.
Wiki (Score:3, Informative)
A fairly simple web application that allows a group to work on documentation together. Since it uses simple formatting rules, it's trivial to learn.
It's the simplest way I know to let a workgroup develop a document.
They have Wiki's that run on Perl, Python, Smalltalk, and PHP so it's easy to find one that you can modify to your heart's content.
Most of the advanced wiki's have all types of bells and whistles (Eg: version control, authenicated users). Some of the wiki's can dump everything from the Wiki database to static HTML or TXT for further processing (which is nice when you actually want to publish).
HTML, LaTeX, LyX., Word... (Score:5, Informative)
A few notes from my experience:
HTML: easy to write, easy to format. HTML TIDY [w3.org] will make everything beautiful for you. HTML actually prints very nicely. I believe most browsers will let you turn off the default page header/footers. I can see, however, that page breaks might be an issue. You'll probably want to use style sheets anyway, and there's a feature in CSS2 that allows for defining page breaks (Paged Media documentation [w3.org]). Also see Converting HTML to other formats [w3.org].
LaTeX: Personally, I'm a big fan of LaTeX. Never tried pure TeX. However, once (if!) I master the CSS2 paged media commands, I'll probably abandon LaTeX. I don't know that one's really any easier than the other; it's just comes down to the simple fact that I know HTML better.
LyX: I found this very non-intuitive and gave up on it quickly. As I recall, the tab key did not work as I expected it, and various things just weren't what I expected them to be.
Word: I know you, the poster, don't want to use Word, so this is for others who must use it. I dislike MS as much as the next /., but I must say that Word is actually a very good product. There are things that annoy me (especially placement of pictures), and there's the macro virus issue, but you probably don't need macros in documentation anyway. As someone else pointed out, there are versioning features in Word. In addition, there are collaboration features that let you track, accept, and reject changes. The style sheets are pretty powerful (most people never use them), and allow you to quickly and easily create tables of contents. And of course, if you're in Windows and have Word already, and assuming it does not constantly crash, it's really the easiest thing to use. Just don't try exporting your document to HTML!
Re:HTML (Score:5, Interesting)
You missed one of the nicest features of using HTML/XML for documention: the fact that with CSS you can get basic content transformation.
What does it mean? It means that you can have rules for online display (that we're most familiar with), different style rules that kick in only when you print (implemented in Mozilla and Opera), and different rules only when you are projecting a presentation (implemented [opera.com] in Opera). This lets you make it accessible on the WWW, yet write your documentation only once without futzing with a nicer "print friendly" copy. If you do a presentation, you can point your audience to the very URL you're using for their later reference. Less chance for confusion.
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.
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.
WordPerfect (Score:5, Interesting)
Not to mention WordPerfect's ultimate advantage over Word: Reveal Codes. In Word, any fouled-up formatting can only be fixed by *different* formatting. In WordPerfect, you can *remove* offending code. And it's more customizable, doing things the way you want them done, not the way Microsoft dictates. I could go on about dozens of other advantages, too.
Oh yeah, there are Linux versions available too (albeit using Wine).
Frankly, I'm amazed that any person with technical knowledge and expertise would use Word by choice.
docbook does work, and works well (Score:5, Informative)
and it works fine.
Grab some emacs elisp files from sourceforge
to round out the package and you are good to go
with tag completion and font color locking
in emacs.
Docbook advantages:
* no worries about formatting, just write content
* can generate html, postscript, possibly wml, carved stone tablets, etc.
* can be parsed by freely available xml parsers
to intelligently extract, say, all authors, all section titles. This could be done with raw
perl, but why rewrite an xml parser when so
many already exist?
* documents can be easily stored in an OODB,
using an xml->object marshaller, if you are
into that sort of thing. This allows
any number of documents to be subject to
the full power of the database querying
and indexing.
Latex (tex) is great, and I've used it for 20 years,
but its definitely not the same thing as docbook.
Latex
allows - encourages actually - one to think
about appearance while writing the document.
And you do get great looking output.
But you sacrifice everything that docbook/xml
offers in terms of document parsing for other
purposes.