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.
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/
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.
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!
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.
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.
I print, therefore I am.
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)
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.
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
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));