Want to read Slashdot from your mobile device? Point it at m.slashdot.org and keep reading!


Forgot your password?

Writing Documentation 583

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?"

This discussion has been archived. No new comments can be posted.

Writing Documentation

Comments Filter:
  • Out of curiousity (Score:5, Insightful)

    by Sheepdot ( 211478 ) on Thursday January 10, 2002 @04:01PM (#2818599) Journal
    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.
  • by Anonymous Coward on Thursday January 10, 2002 @04:02PM (#2818605)
    It will do versioning. See the menu file/versions
    • versioning (Score:2, Interesting)

      versioning is a crucial element to not just documentation, but to methodology as well, in particular with the field I am in, being the pharmaceutical industry. You must be able to see how things like analytic methods have progressed, specifically when moving from development to production. I can easily see parallels between this and programming.

  • try YODL (Score:5, Informative)

    by CommanderTaco ( 85921 ) on Thursday January 10, 2002 @04:03PM (#2818617)
    the samba guys used to use YODL before they switched to docbook. pretty easy to use, and you can convert to other document languages including html, latex, etc.
    http://www.xs4all.nl/~jantien/yodl/ [xs4all.nl]
  • LYX (Score:5, Informative)

    by ocelotbob ( 173602 ) <ocelotNO@SPAMocelotbob.org> on Thursday January 10, 2002 @04:03PM (#2818618) Homepage
    Have you tried LyX? [lyx.org] It's a very powerful multiplatform typesetting program. Seems to do everything you want it to do.
  • Check out doxygen (Score:5, Informative)

    by plalonde2 ( 527372 ) on Thursday January 10, 2002 @04:04PM (#2818627)
    Doxygen [doxygen.org] lets you mark up your source code pretty easily, and generates decent looking documents. You can use the same markup (and cross-reference facilities) in non-code documents processed at the same time.
    • by devphil ( 51341 ) on Thursday January 10, 2002 @05:00PM (#2819151) Homepage

      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.

    • Re:Check out doxygen (Score:3, Informative)

      by Karellen ( 104380 )
      Doxygen is great for producing API references with source code cross-references, if that's all the documentation you need. I've no problems with it there. It rules.

      But for user-level documentation, or even developer-level general overviews of source organisation, resource ownership policies, etc..., I'd have to say it's not the idea tool for that. But then, that's not really what it was designed for.

      I'd take a closer look at Docbook and the fairly large set of untilities that exist for converting it to HTML, TeX, man, texinfo, etc... Check http://www.oasis-open.org/docbook/

      When doxygen's xml/docbook output format is sorted, even this could be moved that way too...

  • full disclosure: I hate documentation (unless its in other people's code ;) and I've been able to luck out in working at places where we need the code written so fast that documentation is an afterthought.

    what about javadoc (is it still called that)? it's good for turning well-formatted function summaries into browsable HTML ....

    Are we talking API documentation here, or real-world english implementation documentation? if you're looking for just a good ASCII editor, straight off, ultraedit is easily my favorite, but if you are looking for stuff to skim your source and rip out inline documentation, obviously, thats not what you're looking for. but javadoc might be?
    • The next time someone asks you that inane question "What is your greatest weakness?" you can just answer that writing documentation is your greatest weakness, but sometimes you've got to do things you don't like to do, so you tend to rely on document generating tools. Nobody likes to do docs, so he'll know exactly what you mean, and you can pat yourself on the back for answering a stupid question in a way that makes you look smart.
  • by deblau ( 68023 ) <slashdot.25.flickboy@spamgourmet.com> on Thursday January 10, 2002 @04:06PM (#2818643) Journal
    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.

  • texinfo (Score:3, Interesting)

    by phr2 ( 545169 ) on Thursday January 10, 2002 @04:07PM (#2818653)
    Call me a throwback or GNU-head but I like texinfo. The stuff you type reflects the structure of your document, it's plain ascii (easy to edit with emacs or your favorite editor), and compiles to online docs, html, or printed docs using TeX. It does make some impositions on your writing style but I find the texinfo formatting commands much easier to deal with than (say) html tags. I use it even when I want plain ascii docs. I just don't put in any "node" commands. Then I run the texinfo doc
    through the emacs formatter and use the formatted ascii output.

    So, it's old and limited but still my favorite.
    • Re:texinfo (Score:3, Interesting)

      by Jason Earl ( 1894 )

      Texinfo isn't at all limited. In fact, it rocks. It has most of the advantages of LaTeX, it generates beautiful looking html, cross-referenced pdfs, gorgeous postscript, and info files to boot. And the Texinfo-mode for Emacs does most of the tricky bits for you. It builds the menus, makes sure the links all go to the right places, etc. etc.

      For computer documentation I personally prefer it over LaTeX (and that's saying a lot).

  • Doxygen (Score:3, Informative)

    by dan g ( 30777 ) on Thursday January 10, 2002 @04:07PM (#2818657) Homepage
    It depends on your specific needs. Are you documenting the source or documenting program usage? For the former, doxygen [stack.nl] may be useful to you. Generates HTML and LaTeX, amongs other formats.

  • JavaDoc? (Score:5, Informative)

    by FortKnox ( 169099 ) on Thursday January 10, 2002 @04:08PM (#2818662) Homepage Journal
    Find something similar to Javadoc (unless you code in Java). Rational has a great set of suites to also document projects.

    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?
  • by seebs ( 15766 ) on Thursday January 10, 2002 @04:08PM (#2818668) Homepage
    I'm doing a bunch of documentation right now, and I *LOVE* docbook. I agree, it's a bit of a pain to set up; we started with openjade as a basis, and worked from there.

    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. :)
    • by PlazMan ( 40335 ) on Thursday January 10, 2002 @04:17PM (#2818757)
      I have to second that. DocBook can be a pain to get started with and learn, partially because it's soooo flexible and powerful. I probably spent a week getting all of the pieces together (editor, DTDs, Xalan, XSL, etc), but now I find it quite easy to churn out anything from a full reference manual to some simple man pages.

      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).
    • by hackerhue ( 182083 ) on Thursday January 10, 2002 @04:24PM (#2818827) Homepage
      I agree. I love docbook. If you can write HTML, chances are you can do docbook. It's plain text, so you can edit it in whatever program you want to.

      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 ;-) ). I use Jade -- openjade seems to be slower, and I couldn't see any advantage of openjade over Jade.

      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.
    • It's not that big of a pain to set up if you have a decent distro that's done the work already. I use FreeBSD, and getting a DocBook environment set up is trivial. It's equally simple under Debian. Slackware has a single package in contribs. Etc.

      If your distro doesn't have a docbook package then it can be a major hassle building and setting it up from scratch.
  • Possible solution (Score:2, Insightful)

    by Fembot ( 442827 )
    HTMLDOC [easysw.com] appears to serve your purpouse. It appears only windows binaries are avalible however but the sourcecode is avalible under the GPL
  • htmldoc is here [easysw.com] .

    This works nicely on very simple HTML (tables, images, font sizes and blockquotes), and is open source. I use it for purposes similar to those requested by the submitter. I write HTML in HotMetal (an easy to use Dreamweaverish thing on Windows) then run it through htmldoc on linux to get a PDF. As far as I can tell you have to settle for Times Roman, Helvetica and/or Courier in the text output. It handles jpegs and non-transparent gifs as well.

    It seems to be abandonware, but it's a handy tool to have around.


    • Abandonware? Quite the opposite!

      HTMLDOC downloads regularly surpass all of our other products combined, and we are actively developing it to support newer stuff like CSS1/2, XHTML, Unicode text, embedded fonts, etc.

      Best of all, of course, is that HTMLDOC is (and always shall be) open-source software, with commercial support for those that need it.
  • by StormC ( 36655 ) on Thursday January 10, 2002 @04:11PM (#2818697)
    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.
    • by klund ( 53347 ) on Thursday January 10, 2002 @04:58PM (#2819127)
      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.

      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.
  • by Enonu ( 129798 ) on Thursday January 10, 2002 @04:11PM (#2818699)
    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 [sun.com] 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.

  • Wiki (Score:3, Informative)

    by Big Sean O ( 317186 ) on Thursday January 10, 2002 @04:11PM (#2818700)
    Try a Wiki.

    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).
  • The Java Development Kit from Sun comes with the javadoc [sun.com] 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.


  • I'm using gobeProductive 3.0.2 on Windows (they have or will have a Linux version). It's like a light-weight replacement for MS Office, done by the same team that did Claris Works for the Mac.

    The word processor is very easy to use, and can save in the gobeProductive format, as well as Word, HTML, PDF, RTF, and plain text.

    The office suite also has spreadsheet, graphics, image processing, and presentation software.

    http://www.gobe.com/ [gobe.com]
  • by Faramir ( 61801 ) on Thursday January 10, 2002 @04:19PM (#2818776) Homepage Journal

    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)

      by ChristTrekker ( 91442 ) on Thursday January 10, 2002 @04:46PM (#2819043)

      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)

      by coyote-san ( 38515 ) on Thursday January 10, 2002 @04:59PM (#2819140)
      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.
      • I completely agree. I want to write in HTML (or some equivalent) and deal with content primarily. Style issues can be left to somebody else that has a clue how things are supposed to "look nice". (I sometimes find myself linking to the W3C Ultramarine CSS, because though I know CSS rules I don't have a sense for style.) If there were a good HTML text (not WYSIWY-won't-G) editor that felt polished (not hackish) I'd love it. Much as I like BBEdit, it's not there yet.

      • Two points: you can turn all that stuff off that you are complaining about and usually that green line is pretty valid, its the user that doesn't understand the problem, like passive voice.
      • by RebornData ( 25811 ) on Thursday January 10, 2002 @07:24PM (#2820289)
        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.
    • 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 [slashdot.org] 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 beg to differ on the LyX issue. I (and many others) find it unbelievably useful, as an easy to use front end to the underlying raw power of latex and friends.

      I personally use LyX not only for technical stuff (physics) but also for software documentation. The manual for my most recent project IPython [colorado.edu] was all written in LyX and from the single LyX source I generate html and pdf versions for distribution.

      I wrote a little perl tool called lyxport [colorado.edu] that automates the process of generating PostScript, HTML and PDF from a single LyX source file.

      With LyX I have a word-processor like environment (but where I can customize everything I want) that handles long, multipart documents flawlessly, cross-referencing, graphics, bibliographies, you name it. And from that single source I get properly subdivided HTML, ready to print PostScript or fully hyperlinked PDF (just remember to use the hyperref package for that).

      I have used MSWord for long documents (100+pages, multi-part with included subdocuments) and it is simply a stupid, devilishly bad joke. It can (I've seen it do it) crash and leave a multi-part document corrupted to the point where the only option is to rebuild the global structure from subdocuments, and the overall design is simply moronic.

      Latex was designed with books and technical documents in mind. Lyx was designed to offer easy access to Latex's power. And side tools can pull them together into a near-perfect environment for what the original poster wanted. And by the way, LyX also handles DocBook if you're looking in that direction.

    • LaTeX vs WYSIWYG (Score:3, Informative)

      by bcrowell ( 177657 )
      The person who posted the original question didn't sound happy about LaTeX's non-WYSIWYG nature. I felt the same way at one time. However, computers are so fast nowadays that the experience of writing in LaTeX can be very much like WYSIWYG. For instance, there are helper apps (e.g. TeXShop for MacOS X) that let you have your source code open in one window and your PDF file open in another. Click a button and almost instantly, you see the result of whatever change you just made.

      WYSIWYG is also a pain in many ways:

      1. You may not be able to tell -- or control -- what's actually in your file. For example, it shouldn't matter whether I type two spaces or one following the period at the end of a sentence -- it should just do the right thing. LaTeX does this, but WYSIWYG software generally doesn't.
      2. There is the temptation to do all your formatting by selecting fonts, etc., rather than by sticking strictly with a stylesheet. For instance, I have some books I wrote in PageMaker, and somewhere inside some of them there is some Geneva, even though I meant to do all the sans serif in Helvetica. I can't find the Geneva! It must be inside a figure somewhere.
      3. WYSIWYG often translates into what-you-want-to-see-is-what-you-have-to-put-in-by -hand. For instance, I have some boilerplate text that appears at the top of the homework problems in each chapter of my books. In LaTeX, if I want to change it, I just change the relevant macro. In WYSIWYG software, I'd have to manually edit every single chapter.

      LaTeX does have some disadvantages, however:

      1. No unicode support.
      2. Setting up a complicated document is extremely difficult and time-consuming. For instance, the .cls file for this [lightandmatter.com] open-source book took me about two weeks to set up.
      3. LaTeX/TeX is a nightmate as a programming language. The code is extremely difficult to read, and since it's a macro language, it's very hard to debug. You end up doing a lot of procedural programming in a language that simply isn't anyone's idea of a good procedural programming language.
      4. Related to LaTeX's macro-language nature is the fact that its error messages are hard to interpret. And there are a lot of them. When I compile my 600-page book, it takes about five minutes for all the warnings to scroll past , at a rate of about a screenful per second!

      Lyx sounds interesting, although I haven't tried it. I'm not sure to what extent it just creates typical WYSIWYG problems while getting rid of typical non-WYSIWYG problems.

      An important consideration is that TeX/LaTeX is open source, and there are free-as-in-beer implementations on virtually every platform. If you're trying to exist in the world of open source, you really need to use open-source tools.

  • WordPerfect (Score:5, Interesting)

    by mkoenecke ( 249261 ) on Thursday January 10, 2002 @04:19PM (#2818782) Homepage
    Remember WordPerfect? Version 9, SP4, is rock solid stable and does not suffer from Word's inability to handle long documents. (The primary culprit: Word's continuous repagination and reformatting, required by the document structure.) Versioning is supported, and WordPerfect, unlike Word, has the native ability to generate PDF files. Version 10, SP2 does even better, formatting hyperlinks automatically in PDF files, but I won't recommend it yet because there's a nasty interaction bug between it and Mozilla.

    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.
    • Re:WordPerfect (Score:3, Informative)

      by istartedi ( 132515 )

      Ugh! One time my room-mate lost a few hours of work due to a corrupted WP file. He asked if I could fixed it. About an hour into carefully studying the revealed codes, I decided I needed some help. So I went to Corel's website. There were literally hundreds of ways that WP files could become corrupted. The problem was particularly heinous because this particular file would cause the entire system--not just WP, to lock up when you cursored into the wrong part of the file. We eventually gave up, and my room-mate reconstructed his writings from memory (human memory that is).

      Of course, that's just one bad experience. Anyone else care to comment about corrupted files in these programs? Automatic backups are always an option, but my room mate did this on a school machine which went down, and he was unaware of that feature anyway.

      Of course the best thing would be to have files never get corrupted in the first place, but if they do it should be easy to recover.

  • by jeffr ( 28143 ) on Thursday January 10, 2002 @04:20PM (#2818792)
    We're using the preloaded docbook on RH7.2
    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.

    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
  • by jelson ( 144412 ) on Thursday January 10, 2002 @04:22PM (#2818811) Homepage
    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 [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.
  • I agree wholeheartedly with your desire to keep the documentation in ASCII text instead of some binary proprietary format.

    I have TeX files from over 10 years ago that

    • were produced on different hardware than I'm running now
    • were produced on a different operating system than I'm running now
    • still can be run through TeX
    • still produce unmatched quality of output, particularly for mathematics
    • can be quickly and easily searched with tools like grep
    • are friendly to the CVS version control system
    and all for free!

    That said, I'm looking into using DocBook in the near future, particularly after seeing how well it's been working for the Linux Documentation Project.

    XML is definitely a good way to go; I'm just not sure if the latest DTD's do a sufficiently nice job on mathematics (via MathML) and on graphics (looking for SVG, not just images).

  • 1. Take a look at literate programming tools, like noweb [harvard.edu] or doc++ [sourceforge.net] (language specific).

    Given the broad nature of you query it's not clear what is most appropriate for you; but literate programming might be what you need.

    2. Framemaker. I've never used it myself, but I have known people who did all of their word processing in it. Pretty output, can do web output too, and definitely intended for larger documents.

    3. Look at [La]TeX again. Seriously. Some of the stuff you need may not be easily provided, but I don't know. Get the book on LaTeX and see if that doesn't handle your previous problems.

  • 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
  • by Genady ( 27988 )
    Really. Most of the programming I do is in PERL, and I had the same problem. There are TONS of ways to convert POD to other formats. Hell The PERL Cookbook was written in POD with some TROFF markup.
  • by Graspee_Leemoor ( 302316 ) on Thursday January 10, 2002 @04:30PM (#2818891) Homepage Journal
    "I have been charged with writing lots of documents"

    ...In the trial of the /. submitter vs the hacker community the defendant was found guilty of writing documentation. He also asked for several charges of using meaningful variable names be taken into consideration.

  • by UsonianAutomatic ( 236235 ) on Thursday January 10, 2002 @04:31PM (#2818906) Homepage
    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.
  • I used to have a lot of trouble in making Docbook work, until I found out KDE's developers documentation [kde.org].

    Install the DocBook parsers and generators:
    http://i18n.kde.org/doc/install/ [kde.org]

    General docbook information:
    http://www.docbook.org/ [docbook.org]

    SGML is the ISO standard for stocking information, and Docbook is the standard for writing books/documentation in SGML or XML. IMHO, it's the way to go.

  • Leo [sourceforge.net] is a programmer's editor that represents a noweb or CWEB (literate) program as an outline. The combination of literate programming and outlining creates a powerful and enjoyable new way of programming.

    Donald Knuth. "Literate Programming (1984)" in Literate Programming. CSLI, 1992, pg. 99. [literateprogramming.com]
    I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming." Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other
  • Not sure what language you're using, but HappyDoc [sourceforge.net] is popular amongst python developers.

    It does a really nice job generating (HTML, text, etc.) documentation from python code __doc__ strings and source code.

  • I like this program called Note Tab for windows. It's downloadable fom shareware.com in a free lite version. It's really quick and easy, but powerful for text editing.

    Nothing beats BBEdit though, nothing. It's only for Macs, which is killing me since I haven't bought a Mac lately.
  • by Anonymous Brave Guy ( 457657 ) on Thursday January 10, 2002 @04:42PM (#2819016)

    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.

  • by klund ( 53347 ) on Thursday January 10, 2002 @04:44PM (#2819029)
    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?
  • I used to use FrameMaker until Adobe started busting [slashdot.org] 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.
  • Framemaker can handle the large documents without the weird problems of Word (losing formatting, text disappearing, crashing, etc). It can format your docs nicely for pretty printouts. And Framemaker documents nicely convert to PDF, since Adobe makes both formats.

    The downsides are that it's expensive (~$800), and it's made by the people who sicced the FBI on Dimitry Sklyarov.
  • The Best Solution (Score:3, Interesting)

    by FFFish ( 7567 ) on Thursday January 10, 2002 @04:59PM (#2819141) Homepage
    There are currently only two good long-document solutions:

    FrameMaker, from Adobe.

    Ventura, from Corel.

    They both have roughly equivalent functionality. FrameMaker is more accepted in the technical writing world. Ventura has a much, *much* better user interface. Ventura also has an incredible user support group. [corel.ca] The latter two aspects put Ventura in the lead by several lengths, in my opinion. A feature comparison is available here. [coreluser.com] (Its automatic database publishing engine is worth it's weight in gold!)

    Ventura is currently in beta-testing for a next-edition release. This edition is going to include XML support, presumably integrated with SoftQuad's products. Given that WordPerfect has had good SGML support for years, I find this to be very, very exciting news.

    If you can get over any misgivings over the Corel name, you'll find that Ventura is the ultimate in long-document publishing. It's been around since 1986, and is more feature-complete than Quark, PageMaker, InDesign, and FrameMaker. And of those, FrameMaker is the only application that can be considered to be in the same class. Quark, PageMaker, and InDesign are short-document (ie. magazine advertisement layout) programs, and are absolutely horrible for use in long-document publishing.

    FrameMaker and Ventura both fully satisfy your needs. Both can take in XML/SGML. Both produce PDF. Both can create HTML. Both handle documents thousands of pages in length with thousands of images. Both kick the living shit out of MSWord!

    You only need to decide which is going to be easier to use, how much you'll want community support, which set of functionality you need, and how much you want to spend.

    My money is on Ventura.

    (It is, in fact, the only application I've ever used that I look forward to using. Every time I start it, I'm delighted!)

    (Ventura users tend to be very enthusiastic about the product. We also tend to wonder why anyone would ever use anything else: we've tried the rest, and figure this is the best. :-) )
    • I tried Ventura 7, which was the first version that Corel wrote pretty much from scratch. This was in early 1997. It was a bad experience.

      First the good points:

      - Ventura had the best user interface of any program I had used up to that time (this alone made me hang onto it longer than I should have).

      - It included lots of drawing tools -- almost a mini-CorelDraw -- that worked right in the document editing window.

      - It was almost endlessly customizeable, in terms of its buttons and menus -- the first program I ever saw that could do so to that extent. I could set it up any way I wanted to.

      Now the bad points:

      - It didn't work.

      That's enough, really, isn't it?

      Ventura broke constantly. It couldn't handle frames. It would sometimes drop characters when it printed files with it (every 'f' on a page would be missing, for instance. Not in the whole document -- just that one page). Sometimes, it would skip whole pages in its output.

      Support was nonexistent. Yes, the newsgroup was great, but the Corel guys kept dropping hints about a patch that was coming out Real Soon Now(tm) that would solve all of our problems. (From those in the know, that patch was called "Version 8").

      After it kept me in the office until 1:30 in the morning, for two nights in a row, trying to print a document that was LESS THAN ONE HUNDRED LOUSY PAGES, I gave up and switched to FrameMaker, and have never looked back.

      I almost did look back, because FrameMaker had such a lousy UI compared to Ventura, and made complicated so many things that Ventura made easy, that I was ready to tear my hair out.

      But Frame's saving grace was: it worked. It worked then, and it works now, and I've never dreamed of giving Ventura another chance. I use FrameMaker almost every day, and have produced documents ranging from 20 pages to almost 400 pages at last count, and FrameMaker has crashed on me maybe four times in four years. It's predictable. It does what it should. And with the addition of mif2go, I can produce HTML, WinHelp, or just about any other markup format as effortlessly as FrameMaker's native PDF support lets me produce Acrobat.

      I've often wondered if they ever worked the bugs out of Ventura, but hey... once bitten, twice shy.
  • roff (Score:2, Insightful)

    by PotatoMan ( 130809 )
    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.

  • Though I initially started using Perl's Pod to embed documentation in my programs, I have found it very useful in other non-Perlish circumstances.

    Pod is not the most sophisticated documentation tool but it has some advantages:
    • Simple syntax. I regularly use 10-15 tags.
    • Can be easily converted to several formats: HTML, LaTex, plain text, man pages, etc.
    • Free with yer basic Perl install

    With a little CSS on the side I have used it for writing articles, creating class presentations, and all the documentation at work.

    Something to consider, especially if your shop has Perl installed already.
  • Try FrameMaker 6.0 [adobe.com] and mif2go [omsys.com] if you want to produce HTML and PDF from the same set of master source files. I've used them with spectacular results, for docs ranging from 20 to 350 pages, including Table of Contents and Index. mif2go does help files, too -- WinHelp, MS HTMLHelp, JavaHelp, etc.

    We have a user manual (350+ pages) and a demo document (~60 pages) that contains a subset of the stuff in the manual. We used to keep one copy of each document in PageMaker (hey, before I came along it was WordPerfect; give me a break!). This required constant, simultaneous editing of the almost-identical sections in both documents. It introduced errors and inconsistencies, and it effectively doubled my editing workload, since the sections we edited most often were the ones in the demo document. Worse, PM isn't suited to long-document problems like re-numbering sections. Any time we added a new section, I had to renumber, by hand, all sections that came after it, including cross-references to other sections (there are hundreds of these). I knew there had to be a better way.

    Three years ago, I switched us over to FrameMaker. Now, I keep ONE set of master documents, from which I produce print, PDF, HTML and Help files for both the manual and the demo document.

    Here's how it works:

    Instead of one big file, I have 31 separate FrameMaker files, each of which corresponds to a section or chapter in the user manual. I have two "book files": one for the manual, which includes all 31 section files, and one for the demo document, which includes only three.

    One of FrameMaker's most powerful features is its "conditional text," which lets you tag certain text for display only on certain conditions. In my case, I created three tags: ManualOnly, DemoOnly and Normal. Most text in all sections is Normal. But, some is ManualOnly and some is DemoOnly; for example, there's a completely different introductory subsection in the demo version of Section 1. That part is tagged DemoOnly; the intro subsection for the user manual is tagged ManualOnly, and the rest of Section 1 is tagged Normal. Now, deciding what gets tagged how takes a bit of work, but once it's done it simplifies things greatly: I open the book file I want, set the display to "Normal" along with "ManualOnly" or "DemoOnly," depending on which book I want, and print. Or, I can save as PDF -- a feature built right into FrameMaker. Note that the sections are numbered differently in the demo document than they are in the manual. That's OK; Frame handles the renumbering automatically, and even renumbers any cross-references between sections as needed! It likewise generates the Table of Contents and Index for me, with page and section numbers as appropriate.

    Now, that works fine for print and PDF. What about Help files?

    This is where mif2go comes in. mif2go generates FrameMaker Interchange Files (MIFs) from your FrameMaker originals and converts them to WinHelp, JavaHelp, HTML, HTML Help, XHTML: you name it. mif2go is US$299, produced by a small outfit called Omni Systems. The price includes free tech support (email only) for a year, and they have been VERY responsive to email, usually responding within the day. The only comparable conversion product I know of for FrameMaker is WebWorks Publisher, which is produced by a self-important corp that charges three times as much for its software that, IMHO, works far less well than mif2go (and yes, I've tried both; a demo version of WebWorks even comes with FrameMaker 6.0).

    Before mif2go, help file creation went like this:

    • export FrameMaker section files to RTF (with FrameMaker's lousy RTF filter), losing most of the markup in the process, such as cross-references.
    • use a HAT (Help Authoring Tool) like RoboHelp to re-format what didn't translate properly, and to replace all the missing links. This usually took about six weeks, and introduced inconsistencies (like spelling mistakes) from the original files. It also had an ugly format, and some tables in our original document just WOULDN'T work no matter what we tried.

    Here's how it works now:

    • Choose File > Save Using Mif2Go.
    • Double-click the .hpj file that mif2go generates, to compile the help using the (free as in beer) Microsoft Help Compiler.

    Done. Perfectly-formatted help files, in less than five minutes. HTML output is much the same.

    I have yet to see anything with the combined power of these two. FrameMaker is available for Windows, Mac and a couple of flavours of Unix (though unfortunately not for Linux), which is a heck of a lot better than you can say for LaTeX, which I wouldn't touch with a barge pole. For serious document work, give me WYSIWYG anytime: I can manage the layout -- even simple things like widows and orphans -- much more easily in a GUI than I can from a basic text editor.

    And finally, FrameMaker is rock-solid. I use it every day, for serious work, and it has crashed maybe four times in the three years I've used it. I can't think of any other piece of Windows software that has been so reliable.

    A word of warning: I've made this sound like a Great Thing, and it is. But it's not easy to begin with. FrameMaker has a pretty steep learning curve; it's been said that you can do anything to a text document with Frame, but nothing easily. However, your coding background will probably give you a great headstart. Some of the things, like the automatic renumbering of sections and cross-references I mentioned, will be much easier to set up, for example.

    Good luck -- and stay away from Word.

  • I see some posts from people talking about DocBook as if it's an application-- it's not. Docbook is a DTD (Document Type Declaration): it's a specification of tags used to markup documentation, much like HTML's DTD (http://www.w3.org/TR/REC-html40/sgml/dtd.html) describe those tags used to mark up a web page.

    So, like, documentation written using the DocBook DTD will look something like a web page, only the tags that surround the content are specific stuff you'd find in documentations. Some of the tags look like this:


    All you really need in order to write documentation in DocBook is an editor that can handle SGML or XML and can use DTDs. Files marked up using DocBook are simple SGML (or XML) text files, and you can alter how they are displayed or printed with .CSS just like a web page.

    So you can have a single source for all your documentation, such as a manual for your software, and output from docbook to any other format-- PDF, HTML, XML, or print.

    There are lots of open source programs out there for writing XML files that let you import a DTD, some of which are specifically geared towards Docbook. Other applications take files marked up using DocBook and, along with a .css file to say how to display each of the tags, convert/format them into whatever you want: .eps, .pdf, .html, etc.

  • DocBook is my choice (Score:2, Informative)

    by slagdogg ( 549983 )

    I've gone through a similar struggle, trying to find a documentation format that is more flexible and less frustrating than Word. My motivation for the change was that I was unproductive working with Word, mostly because there was too much time spent trying to make the tool work the way I wanted it to. Also, seemingly simple tasks like trying to create a table of contents were much too burdensome.

    I started with HTML. I figured that HTML would be a nice choice, because it's relatively standard and I could use a more sensible editor. I wrote a document of two in HTML, but in the end I found myself to be just as unproductive in HTML. I spent too much time worrying about formatting this and that, and it felt like quite a mess when I was finished.

    I looked into the alternatives, and I kept finding the word DocBook coming up. The FreeBSD and LDP teams were using it, and so I felt it was worth a look. It seemed a bit intimidating at first, until I realized that a simple 'apt-get install sgmltools' was all I needed to get started. There are plenty of sample DocBook documents lying around on any 'NIX box, or on the web. So I started by just editing the samples.

    I haven't looked back -- it's so productive to write documentation in DocBook. Instead of wondering "How should I format this product name ... should I use bold? Italics?" you just wrap the product name in a 'productname' tag. All the output is handled with a few simple commands.

    Another nice feature of using DocBook is when combined with CVS. The text based format is great for performing diffs, and it also lends itself well to concurrent documentation writing. It's great when two separate developers can each take a section in the same file, again boosting productivity. Finally, there is a great IDE for DocBook -- emacs with PSGML mode ... it eases a lot of the tedious tasks such as entering end tags, and handles formatting and indentation wonderfully.

    I encourage you to take the time to learn DocBook, it's very simple to get started, and has made my documentation writing a much easier process.

    Good luck!

  • NegWeb [boswa.com] is a "semi-literate" programming tool. Basically, it lets you define chunks of output files in any order, in any location in input files. So if you want to put the chunk of documentation for a feature in LaTeX or HTML just before the chunk containing its implementation, you are free to do so.

    It differs from other literate programming tools in that it doesn't have any concept of formatting the NegWeb source as a whole. Literate programming started with Donald Knuth's WEB, which arranges Pascal in the same way that NegWeb arbitrary text files (an operation called "tangling," since the results are compilable, but not pretty), but also indexes and pretty prints the Pascal and treats the text between the code chunks as TeX (called "weaving"). Knuth later created CWEB, which does the same thing, but for C instead of Pascal.

    My problem with this approach is that when you go to edit it, you deal with the ugly TeX source, or you reweave constantly. Also, unless you are such a TeX wizard that you do it without ever thinking or looking things up, you are distracted from working on your functional output by fiddling with the formatting. The NoWeb approach is to have the plain text source the most readable version of the source, on the principle that code is most often read to be edited.

    The name is a play on NoWeb, which is essentially a simplified and generalized CWEB, since NegWeb is essentially a simplified (some literate programmers would say "crippled") and generalized NoWeb. NoWeb is very extensible, and supports indexing and pretty-printing for a lot of languages, as well as using several different formatting languages for weaving, such as LaTeX and HTML.

    Either would work for rearranging arbitrary ASCII text chunks into files: NegWeb [boswa.com] is simpler, NoWeb [harvard.edu] is prettier.

    You might be surprised at the freedom it gives you to factor your code into short, manageable chunks. It definitely helps to set up a few macros in your text editor to treat the chunk names as hyperlinks to find the definition of the chunk, and all places it is used.
  • by swillden ( 191260 ) <shawn-ds@willden.org> on Thursday January 10, 2002 @05:28PM (#2819479) Homepage Journal

    I've been using XML and Docbook for a while now, and I really, really like it, particularly if you use Docbook as an intermediate format rather than what you actually write your documentation in.

    For example, I've got some really nice stuff for building use cases in XML. I created my own DTD for a use case language (which I call UCML) that allows me to define actors, use cases, goals, glossary terms, etc. Use cases consist primarily of a sequence of steps (nestable) with links to actors, terms, other use cases or steps, goals, etc. along with some other tags that define the name, extends relationships with other use cases, termination states and conditions, preconditions, business rules, etc.

    I also have some XSLT stylesheets that do a number of nifty things with these UCML documents. One stylesheet transforms UCML to HTML, complete with every imaginable hyperlink, tables of contents etc., and even deduces a bunch of relationships which it documents (and hyperlinks). For example, if a use case mentions an actor or another use case in its steps, the stylesheet adds a section to the HTML description of that use case that documents the fact that this use case uses (in the OO sense) that one, or that this actor participates, and adds similar information to the descriptions of the use case and actor that are referenced. This is just a sample, the stylesheet does a lot more, and produces very *usable* and consistent documentation.

    Another stylesheet acts as a sort of garbage collector. Phases (groups of Use Cases intented to implemented together) and Use Cases can be marked as "dead", in which case the UCML->HTML stylesheet will "hide" them (they won't show up in the output). The garbage collector stylesheet takes this a step further and analyzes all actors, glossary terms, entities, goals, etc. and produces a new UCML document that does not include elements unreferenced by a "live" use case. So, I can mark some currently uninteresting use cases as dead, run the garbage collector, run the UCML->HTML stylesheet on the result and get a nicely formatted document that contains only the supporting information required for the included use cases.

    HTML is not ideal for printing, though, and this is where Docbook comes in. I have a UCML->Docbook stylesheet that does essentially the same things as the UCML->HTML stylesheet. Then I can convert the Docbook to PDF, Postscript, TeX, etc.

    I've also created my own XML languages for component models, architectural decisions documents and others -- it's pretty easy to gin one up whenever I come across another sort of highly structure document I need to write. Plus I have one that I use for simple, less-structured documentation that just provides sections, paragraphs, etc. Mostly I just have whatever->HTML stylesheets for most of these, since they're all intended to be read by developers who are less insistent than end-users on having printable formats.

    So, I have nice, text documents that I can use EMACS on, manage in CVS, etc., stylesheets I can fiddle with (when I get sick of writing documentation I can always spend a little time improving the stylesheet code and justify it as "documentation" effort :-) ) and everyone else gets really nice docs from me. The biggest downside is that other people (non-programmer types who are uncomfortable with tagged text) are often uncomfortable with trying to edit my documents (sometimes it's a good thing, as it allows me to retain the "power of the pen", sometimes its bad as even trivial updates must pass through me).

    The next steps with UCML are (1) figure out how to establish and maintain XMI-documented use cases and UCML-documented use cases and (2) write a WYSIWYG-like tool for editing them, for the tag-averse.

    BTW, if anyone is interested in using the stuff I've described, drop me a line. I've been thinking about putting it up on SourceForge, but don't know if there's enough interest to make it worthwhile.

  • In praise of DocBook (Score:5, Interesting)

    by PhilRod ( 550010 ) on Thursday January 10, 2002 @06:08PM (#2819778)
    Nobody seems to have mentioned the great advantages of DocBook here. Having written some bits of documentation for KDE, I've seen some of DocBook's advantages:
    • First off, it's fully compliant SGML or XML, whichever flavour you prefer. DocBook documents are stored as nice plain ASCII which can be processed with any SGML/XML tool you happen to have lying around.
    • Output options are virtually unlimited. IIRC, HTML, man, texinfo, plain text, (La)TeX and anything else you care to mention are available as output formats, with XSL providing a way to produce your own custom output.
    • The Crunch: Text is marked-up for what it is, not what it's meant to look like, so you needn't know a single thing about formatting while writing content and vice versa. You know the advantages of using CSS instead of hard-coding HTML. Well, they count for DocBook too.
    • Nifty features like creating tables of contents from the source and all that sort of thing that you thought only TeX could do.
    • I suppose I should mention that it's extensible, hence the XML version.
  • Apache Cocoon... (Score:3, Informative)

    by graveyhead ( 210996 ) <fletch AT fletchtronics DOT net> on Thursday January 10, 2002 @06:28PM (#2819912)
    apache cocoon [apache.org] is an awesome publishing tool. I recently created a site that creates a web site and a series of PDF documents from the same source. Your input documents are as simple as you want them to be, because you define it yourself and transform it into HTML or XSL:FO via XSLT.
  • Use an Outliner (Score:3, Interesting)

    by Lysander Luddite ( 64349 ) on Thursday January 10, 2002 @06:53PM (#2820080)
    Use an outliner. There are several out there, the one that springs to my mind immediatley is Omni Outline (www.omnigroup.com).

    Using an outliner allows great hierarchical structure allowing you to edit quickly.

    A good outliner will also output to HTML/XML where you can apply a CSS file for both screen/print mediums. Mozilla, even IE 5+ will ensure your docs appear how you want. Heck, you can change the CSS file and not worry about the presentation at all. Just create a few CSS templates and off you go.

    I don't know why you'd make it harder than you have to.
  • by beej ( 82035 ) on Thursday January 10, 2002 @07:09PM (#2820189) Homepage Journal
    I've done Beej's Guide to Network Programming [csuchico.edu] in DocBook (it used to be HTML). It works quite nicely for HTML output with NWalsh's stylesheets.

    What was hard was getting it set up, and getting help out of the DocBook people in the know. (They can be pretty unapproachable sometimes.)

    What was also hard was getting print output to work nicely. I was running fine for a while until I upgraded openjade, and then blammo--two-sided print output doesn't work anymore. Openjade simply refused to put the two-side directive in the TeX output, so I did it myself.

    And what is it about my document that causes openjade to take 3 minutes to pump out TeX output, when it does the HTML in about 5 seconds?

    Why is it that when I put two tables on the same page openjade/jadetex doesn't take that into account and keeps printing text off the bottom of the sheet?

    The other place I've looked is Xerces/Xalan/Fop at Apache [apache.org]. I like the Formatted Objects idea, and it seems pretty sound. Also, the whole thing was about 827 times easier to set up than the jade stuff. Unfortunately, the code is alpha and doesn't work very well, sometimes crashing during the render.

    "How does ORA do it, then?" I hear you asking. They have custom in-house tools for processing DocBook that have been in development for some time. Word on the street is that they might be releasing them soon.

    Conclusion: if you want print output, you might have trouble getting what you want with DocBook at this time. At least when I code TeX it does what I say. (I don't recomment plain TeX for documentation. Maybe LaTeX since it's easier to convert to HTML. And pdf(la)tex produces nice PDFs.)

  • texinfo or docbook (Score:3, Informative)

    by runswithd6s ( 65165 ) on Friday January 11, 2002 @01:21AM (#2821743) Homepage
    info(1), IMHO is one of the best on-line document readers I've ever used. I liked it when I first was acquainted with gcc. Type in 'info libc' and you get a full libc reference book! With examples!

    Ever thought man pages were limited in that you couldn't automatically go to a referenced manpage? Use info, hit tab until you reach the reference, then hit enter. Walla!

    Yes, info has become my all-time favorite. Far beyond the limited HTML markup. Not convinced? I would like to bring to your attention a few posts already made concerning info(1) and the document format texinfo: 2818653 [slashdot.org] and 2819778 [slashdot.org]

    I've recently started the chore of changing an existing TeX document into texinfo format. I would have loved to use a converter or a formatter from TeX to texinfo, but alas, such a tool was not available. vim's search and replacement works pretty well. Regardless, since texinfo docs can create TeX, XML, and HTML documents, I believe it's the best of the docformat-to-docformat wars. Additionally, it's a pretty simple markup to use.

    Check out info2www [ericsson.se] by Roar Smith [mailto] for a simple way to push out your installed info docs.

    Here's the GNU Texinfo [gnu.org] documentation.

    The only other acceptable format, IMHO, would be docbook.

I am a computer. I am dumber than any human and smarter than any administrator.