Slashdot Mirror
Writing Documentation
"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?"
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/
Have you tried LyX? It's a very powerful multiplatform typesetting program. Seems to do everything you want it to do.
Marxism is the opiate of dumbasses
Doxygen 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.
I have the same "problem" and I use XML for the document source. Using XSL (xalan/xerces or any other xsl/xml library) I transform it into HTML, PDF, ...
A perfekt solution!
It depends on your specific needs. Are you documenting the source or documenting program usage? For the former, doxygen may be useful to you. Generates HTML and LaTeX, amongs other formats.
dan.
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?
Good quote, too many chars. Seriously, the slashdot 120 char limit sucks!
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.
My blog: http://www.seebs.net/log/ --- My iPhone/iPad app: http://www.seebs.net/seebsfrac/
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.
----
mt
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).
My father is a blogger.
Word's versioning is awful. Documents often corrupt because of it. Also, the "latest version" of your document contains ALL revisions of the document, leading to huge files. Did you save 50 times? Then your .doc will be 50x larger than it should be.
How about doing a search on google? I've yet to come across a question/problem that somebody else hasn't had. I typically start by searching the regular sites and then switch to the newsgroups (groups tag on google).
A few notes from my experience:
HTML: easy to write, easy to format. HTML TIDY 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). Also see Converting HTML to other formats.
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!
If you're interested in in-line documentation extractors and processors, which I recommend, check out JavaDoc (which ships with the JDK), and it's C++ equivelant, DOC++. Both are very easy to learn. I've found the quality of my documentation has doubled since I've started using these tools. They allow you to write docs at the same time you write code, in the same files. It also gives you the feeling that you're writing the documentation for a purpose, rather than just "bolting it on" afterwards.
Good luck.
in particular these resources
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.
Latex
allows - encourages actually - one to think
about appearance while writing the document.
And you do get great looking output.
But you sacrifice everything that docbook/xml
offers in terms of document parsing for other
purposes.
For an XML and PDF based solution, check out FOP from the Apache XML Project. Based on XSL Formatting Objects, an upcoming W3C-standard. It rocks!
I used to have a lot of trouble in making Docbook work, until I found out KDE's developers documentation.
Install the DocBook parsers and generators:
http://i18n.kde.org/doc/install/
General docbook information:
http://www.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.
A user level app shouldn't crash from anything a user does to it. Period. If it does, than either there's a fault in the app or a fault in the OS, and it's usually in the app.
Correct and complete error checking is difficult, and I've messed it up more times than I'd like to admit. But darn it, I do try. I once had a professor who showed us two versions of the same program, one with error checking, and one without. The one with was easily four or five times as large as the one without. On the other hand, it didn't crash. (As far as I know.)
It's not the same as driving a car. Within an application you can anticipate all possible ways of use and limit the user to those things which make sense. An auto manufacturer can't keep a stupid person from driving into a brick wall without causing the car to be useless in the process.
Sean.
Everywhere I go, the doc writers are either using Framemaker, or switching from Word to Framemaker.
t ml
Framemaker is the king of structured documents. And it runs under Unix, albeit Solaris or AIX or HP-UX (but it is in X Windows).
http://www.adobe.com/products/framemaker/main.h
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.
My word processor was written by Stanford Professor Donald Knuth. Who wrote yours?
We're using Doxygen to generate HTML and man pages (!) for libstdc++-v3, 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.
You cannot apply a technological solution to a sociological problem. (Edwards' Law)
Pod is not the most sophisticated documentation tool but it has some advantages:
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.
The main problems with using dvipdf rather than pdflatex are:
1) The generated pdf files are larger than necessary, since semantic knowledge of the document has been lost between source and dvi forms.
2) All hyperlinking is lost. pdflatex does a wonderful job of hyperlinking, whereas dvipdf does not have enough information to do so.
Jason Evans
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!
(Score:-1, Wrong)
WYSIWYG is also a pain in many ways:
LaTeX does have some disadvantages, however:
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.
Find free books.
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.
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.
For all intensive purposes, "whom" is no longer a word. That begs the question, "who cares"?
StarOffice 6 uses a new file format which amount to a pkzipped archive containing four standard XML documents and in line objects as seperate files.
I've used both Staroffice and Tex extensively to document networks for customers at my workplace. And I think Tex is in zombie mode now - dead, but not quite realizing it.
Tex:
* Attempts to seperates content from presentation
* Can automatically produce some parts of a document based on others
* Is hand editable in plain ASCII
* Exports to many common file formats
It also:
* Uses metafont, a font system that is unlike every other modern Unix application in existence and is designed around the use on non scalable fonts
* Has non-programmer editing tools which still aren't really suitable for end users and don't produce the output intended.
StarOffice 6 contains all the advantages above - content and style can be kept seperate, the text file format is plain ASCII, stylesheets are used, and StarOffice can export to a lot more fileformats than tex can via the use of XSLT and StarOffice's own inbuilt filters.
The GUI editing program also shits all over the Tex tools I've used - a simple Word Processor application with 2 additions:
* The stylist, a style pallette which applies styles to parts of content and allows the editing of those styles
* The Navigator, a floating window which provides a heirarchical view of the document allowing the author to immediately see and edit the structure of the content as well as move to different parts of it.
Hence its pretty easy for a non programmer to produce a real structured document without extensive knowledge of the system. People who write good documentation are often non programmers - they write documentation from an end user POV for their fellow end users, and if the end users aren't programmers, the documentation person doesn't have to be either in my opinion.
Of course, you can always produce and manipulate StarOffice 6 documents from your text editor, shell or other scripts. I'm working on converting our old Tex documentation script to produce SUn XML Writer documents as we speak.
Oh yeah, and no more jumping through hoops deadling with metafont shittiness. Yay.
Its a pity the 6.0 beta crashed on the poster - personally I find its the most stable and fast StarOffice yet, and that 5.2 was flaky, especially with net installs.
apache cocoon 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.
std::disclaimer<std::legalese> sig=new std::disclaimer; sig->dump(); delete sig;
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.
"Karma can only be portioned out by the cosmos." -Homer Simpson
*SHHESH* !!!!
.sig was right: "Putting a lameness filter on Slashdot is like putting a shit filter on your ass!!!"
FINALLY, a post which really talks to the question this thread was started for!!!
Damn that
We _all_ have to, at one time or another, create documentation for something. I have to create documents for the Luddite users on my network so they know how to keep their trousers from becoming unzipped in front of their customers...
I have used Word on a great many of these documentation projects, great *and* small. It has always performed fine for me. There are a crapload of features I'm sure I could be taking advantage of to make my documentation even snazzier but I'm too lazy to really LEARN Word. Like as not I've been holding out for an Open Source alternative like Star Office or something to step up to the plate...and the latest version really holds up well. Compatibility with MS-Office's formats helps a great deal with the transition and it is available for Windows AND *n*X.
For exeptionally large jobs, I would recommend an actual professional layout package like PageMaker/FrameMaker on the closed source OS's. For simplicity's sake, TeX and LaTeX for simple ASCII-text-with-markup in them.
Your subject and your audience really dictate the format and platform of your documentation. A new version of Apache doesn't come with a README in Word/RTF format but your latest FPS game will.
-PONA-
King of the Who?.sig
+that's funny...I don't FEEL tardy.+
Yes, the idea with literate programming is that the documentation and code is all one file. It prevents the whole "Oh, now I need to do the docs." problem, and the problem where the documentation diverges from the actual code. If you change the code, you change the documentation right in the same file next to the code. I find noweb to be an interesting tool. It is Latex and Lyx aware. The one page document on noweb below is very informative: Onepage guide to noweb
I realize this is a bit off topic, so I apologize in advance.
From the \begin{equation} and \end{equation} macros, I'm guessing that you're using LaTeX. If I'm right (and you feel a need to define abbreviations for these two macros instead of using them as-is), you might try \newcommand{...} instead of \def. Of course, if you don't need the numbering, \[ and \] are acceptible shortcuts (if you do need the numbering, you could always check into renewing \[ and \]).
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 and 2819778
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 by Roar Smith for a simple way to push out your installed info docs.
Here's the GNU Texinfo documentation.
The only other acceptable format, IMHO, would be docbook.
assert(expired(knowledge));
http://www.ntg.nl/context/
:(. Use PDF :)
Very nice, clean macro set. _Much_ better than LaTeX if you want to change the look of your documents.
Powerful toc/index capabilities. Powerfull PDF creation w. automatic linking.
You can use XML as input language.
_Very_ nice. Took me one day to learn, after that two hours to create the formatting style for writing contracts. I couldn't have done that in LaTex.
No html