Writing Documentation 583
"So far, I like aft,
mostly because it is simple to use, and gives me nice result as HTML.
Unfortunately HTML is not enough, since I also need a very good looking
printable version.
There are alternatives like DocBook,
which I could not get to work and udo
(Page is German, get the translation from the fish) which I have not yet looked
into very closely.
Then of course there is TeX and any number of WYSIWY-won't-G word
processors. I haven't used TeX much, I only tried my luck in writing
a few letters (and found out that it is not suitable for this). I went
through hell when I wrote larger documents with various versions of
MS Word and I am not really a fan of Star Office even though version
5.2 has not yet crashed on me (however 6.0 beta did). KWord, part of
KOffice doesn't seem to be stable enough yet.
I would prefer a simple ASCII only format as the source for being
converted to more complex formats anyway, especially since it could
be easily put into CVS for version management (Anybody tried that
with MS-Word documents? Don't!)
As all these projects show I am not the first one faced with this
problem. I wonder what experiences Slashdot readers have had with
these and other packages?"
texinfo (Score:3, Interesting)
through the emacs formatter and use the formatted ascii output.
So, it's old and limited but still my favorite.
versioning (Score:2, Interesting)
Custom Format (Score:1, Interesting)
If you're writing actual user documentation, i'd suggest using a flat text format with some delimeters in it, and then use perl to process that into HTML, TeX, or whatever intermediate format you'd like, and then process that into your PDFs using any of the available tools.
Pros: you control the entire process, so it comes out just how you want it. the filters you write can be stored in CVS right next to the documents they're run against, so you can track changes easily
Cons: you have to use Yet Another Language. you have to maintain things. you lose the "look and feel" of certain generators.
overall, i like the tradeoff, but i'm also notorious for being picky about things being Mine.
Re:PEBKAC (Score:3, Interesting)
Sometimes it is the hardware, malicious programs, other programs, or the operating system too.
You're right that it isn't the user's fault, but the blame can fall on any of the developers of any running software or hardware on the system, not just the application's developer.
Or, to sum it up, blame microsoft since they do it all
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.
Re:PEBKAC (Score:1, Interesting)
98-99% of application crashes are the developer's fault... the rest, either dumb user of dumb hardware.
Re:PEBKAC (Score:3, Interesting)
I would edit your statement to say something more along the lines of:
If an application crashes while being used as it was intended, it's the developer's fault.
LEO, Donald Knuth & Literate Programming (Score:2, Interesting)
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
The problem I have with Documentation Systems (Score:1, Interesting)
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.
The Best Solution (Score:3, Interesting)
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.
FrameMaker + mif2go = almost any output you like. (Score:2, Interesting)
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:
Here's how it works now:
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.
Re:texinfo (Score:3, Interesting)
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).
Re:Word is horrible (Score:2, Interesting)
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.
XML, XSLT and Docbook - a near-perfect solution (Score:5, Interesting)
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.
Re:Documentation is not evil! (Score:2, Interesting)
Lets look at how a house is built, is all of the time spent in spec and design. Do they write a document outlining how the tub will be installed in the top floor bedroom?
No, they provided a picture of what they want. (Detailed mind you, but still is just a picture.) From that the construction company builds it. The builders never get a step by step checklist.
But when it comes down to documentation (At my company at least) They want everything, what classes are there, what methods, how the code will be written, yada, yada, yada.
While this information might be interesting, it is not useful! It means nothing to the end product, or to even maintenance of the code. If you have done any type of maintenance to code you know the only way to do it is to read the code!
As long as you have a clear picture of what to build you can create the product, and then SELL it! Excessive documentation only slows the development process and adds to a company's bureaucracy.
In praise of DocBook (Score:5, Interesting)
- 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.
--PhilRodTeX 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
Use an Outliner (Score:3, Interesting)
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.
Be a little wary of DocBook (Score:4, Interesting)
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.)
It depends... (Score:2, Interesting)
1. Interface/API documentation: Here I normally generate latex from the C++/Java/C sources with DOC++ [www.zib.de] and publish it as PDF's. I could generate HTML but most of my collegues agree with me that printed documentation are nicer.
2. User Manuals: It varies. troff for man pages, Latex for hardcopies, M$ Word if nontechs has to edit/localize the stuff.
3. Tech Specifications, Software Design Documents: Such documents are mostly used within the company by the tech staff, so I use Latex for formatting and M$ Visio (and sometimes some fourth-generation tools such as Erwin or Rational Rose) for diagrams. It works for me! And these can be put under source control (we use CVS).
4. Collaborative documents: Such as proposals, RFPs, Site Acceptence Test documents that non-techies (Account and Project managers most of the time) has to edit.. For these I use M$ Word/Excel and I must admit I use a considerable amount of time on the things that LaTeX does automaticially for me - that is layout and presentation.
As a rule of thumb I always submit documents as PDFs. Good luck and always remember YMMV!!
Re:No, you're an idiot (Score:2, Interesting)
I'm almost sure that that isn't true. Of the five people that I know who are writing dissertations at the moment, one is using Word, three are using LaTeX, and one is using something else (can't remember what, but it's neither of those two).
Word, by default, thinks about presentation first. I realize that your arguements state that all the defaults can be changed, but for the most part, people don't. It's very difficult to fix all the defaults, and when you go to another computer to try to fix things, you usually have to work to get things back to the way that you want them.
Also, Word is bloated. How many multi-hundred page documents have you seen written in word? In my and my friends and colleagues experiences, it starts choking around 20 pages and dies around 50. Start adding images/figures and it'll sputter to a halt about one less page per 50K of image or per figure.
I just finished writing a rather long document (about 40 pages), and the time that I spent on content was negligable. I adjusted the margins primarily. The system that I used is LaTeX. It worked out that I just use \filename{} to indicate a file name or directory. I used \button to indicate a button that I pressed. These were then defined at the beginning and I never think of them again. Also, it allows me to save the time of opening a massive editor (at least 20 seconds to load word on my computer while emacs loads in less than 5) each time I have to edit.
I use word for < 5 page or < 10 page documents, but it isn't designed well by default for large complex issues. It can do them, it just takes more work than other systems.
I would be interested to hear your rebuttal to these comments (unless you decide to flame).
LaTeX2HTML not a complete solution (Score:2, Interesting)
It's not a bad program, but YMMV for actual use. (Note: I make my comments after writing a 100 page product manual in LaTeX.) OTOH, I must admit that a printed LaTeX document is a thing of beauty. If you're serious about using it, you definitely need to buy a book or two (say Lamport's and one more comprehensive reference).
If you're starting from scratch though, maybe you should give DocBook a proper go, given that it is supposed to be the format of the future and subsume all others.
Cheers,
Ade_
/
Re:PEBKAC (Score:2, Interesting)
I find word very cumbersome when trying to format documents correctly. Though earlier this week I found a cute way of formatting documents properly in Word:
I use a wiki [usemod.com] for my own documentation - nice simple stuff like == 2nd Level Heading == and a few in-line HTML tags.
I then copied the htmlised text from IE5, pasted it straight into word - self formatted - looked like any other document we have here.
The bonus of this trick is that I've built myself a wiki to DocBook converter (partial at the moment), so my wiki is a neat document management system that I can use from any web browser.
I'm a big fan of wiki's - its a useful catch all solution