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?"
try YODL (Score:5, Informative)
http://www.xs4all.nl/~jantien/yodl/ [xs4all.nl]
LYX (Score:5, Informative)
Check out doxygen (Score:5, Informative)
And the solution is ... (Score:1, Informative)
A perfekt solution!
Doxygen (Score:3, Informative)
dan.
JavaDoc? (Score:5, Informative)
And I don't think "documenting" is the worst part of programming. Its very sterotypical.
I love design, and document while coding (usually in Java with Javadoc comments). Isn't that the way you are supposed to code?
Especially in a team environment (even more "especially" with Open Source), documentation is critical. Having a good design documented well is how developers should interact with one another.
Also check TogetherSoft. They have software that creates the UML while you code.
I also like Together's identification of titles. A "Developer" is someone that designs, codes, and documents. A "Coder" is someone that codes. Which are you?
Docbook, docbook, docbook. (Score:5, Informative)
Still, I love the format; it's clear, it's precise, and it's very well-suited to documentation.
BTW, I'd like to point out that, if you think documentation is the worst part of programming, you're probably not writing very good documentation. Documentation can be a lot of fun. Think of it as a way to make sure that you won't have to do the maintenance later, because anyone will be able to do it based on your writing.
convert simple html to pdf (Score:2, Informative)
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.
----
Wiki (Score:3, Informative)
A fairly simple web application that allows a group to work on documentation together. Since it uses simple formatting rules, it's trivial to learn.
It's the simplest way I know to let a workgroup develop a document.
They have Wiki's that run on Perl, Python, Smalltalk, and PHP so it's easy to find one that you can modify to your heart's content.
Most of the advanced wiki's have all types of bells and whistles (Eg: version control, authenicated users). Some of the wiki's can dump everything from the Wiki database to static HTML or TXT for further processing (which is nice when you actually want to publish).
Re:A point about M$ word (Score:1, Informative)
Re:About Microsoft Documentation @# +4 : Bingo #@ (Score:1, Informative)
Re:Docbook, docbook, docbook. (Score:4, Informative)
I finally found Morphon's XML Editor [morphon.com] and have been quite happy with it for editing DocBook documents (despite the fact that it's currently a beta version that will crash once in a while).
HTML, LaTeX, LyX., Word... (Score:5, Informative)
A few notes from my experience:
HTML: easy to write, easy to format. HTML TIDY [w3.org] will make everything beautiful for you. HTML actually prints very nicely. I believe most browsers will let you turn off the default page header/footers. I can see, however, that page breaks might be an issue. You'll probably want to use style sheets anyway, and there's a feature in CSS2 that allows for defining page breaks (Paged Media documentation [w3.org]). Also see Converting HTML to other formats [w3.org].
LaTeX: Personally, I'm a big fan of LaTeX. Never tried pure TeX. However, once (if!) I master the CSS2 paged media commands, I'll probably abandon LaTeX. I don't know that one's really any easier than the other; it's just comes down to the simple fact that I know HTML better.
LyX: I found this very non-intuitive and gave up on it quickly. As I recall, the tab key did not work as I expected it, and various things just weren't what I expected them to be.
Word: I know you, the poster, don't want to use Word, so this is for others who must use it. I dislike MS as much as the next /., but I must say that Word is actually a very good product. There are things that annoy me (especially placement of pictures), and there's the macro virus issue, but you probably don't need macros in documentation anyway. As someone else pointed out, there are versioning features in Word. In addition, there are collaboration features that let you track, accept, and reject changes. The style sheets are pretty powerful (most people never use them), and allow you to quickly and easily create tables of contents. And of course, if you're in Windows and have Word already, and assuming it does not constantly crash, it's really the easiest thing to use. Just don't try exporting your document to HTML!
Re:Documentation is not evil! (Score:1, Informative)
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++ [sourceforge.net]. 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.
TEX / LATEX resources (Score:1, Informative)
in particular these resources
docbook does work, and works well (Score:5, Informative)
and it works fine.
Grab some emacs elisp files from sourceforge
to round out the package and you are good to go
with tag completion and font color locking
in emacs.
Docbook advantages:
* no worries about formatting, just write content
* can generate html, postscript, possibly wml, carved stone tablets, etc.
* can be parsed by freely available xml parsers
to intelligently extract, say, all authors, all section titles. This could be done with raw
perl, but why rewrite an xml parser when so
many already exist?
* documents can be easily stored in an OODB,
using an xml->object marshaller, if you are
into that sort of thing. This allows
any number of documents to be subject to
the full power of the database querying
and indexing.
Latex (tex) is great, and I've used it for 20 years,
but its definitely not the same thing as docbook.
Latex
allows - encourages actually - one to think
about appearance while writing the document.
And you do get great looking output.
But you sacrifice everything that docbook/xml
offers in terms of document parsing for other
purposes.
FOP (Score:1, Informative)
Re:Docbook, docbook, docbook. (Score:4, Informative)
It's a bit of a pain to set up, but once it's going, it's great (much like most of Linux, I find
My only complaint about docbook is that it (currently) doesn't do math too well -- I use Walsh's stylesheets, and they don't seem to grok MathML yet -- so I have to stick with LaTeX for some things still. Oh, and its table support doesn't seem to be complete when using the TeX backend, so things may come out in unexpected ways.
Re:Docbook, docbook, docbook. (Score:2, Informative)
If your distro doesn't have a docbook package then it can be a major hassle building and setting it up from scratch.
Docbook explained by KDE's team (Score:2, Informative)
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.
Re:convert simple html to pdf (Score:3, Informative)
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.
Re:PEBKAC (Score:2, Informative)
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.
Framemaker (Score:1, Informative)
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
Re:LaTeX seemed the simplest way (Score:5, Informative)
In addition to producing HTML and PDF with latex2html and pdflatex, there are some other features in TeX/LaTeX that appeal to code monkeys like me.
1. Real include files. For example, you can write a mission statement page that gets included in the front of all your documents. When the mission statement changes, you only have to update it in one place, and all your documents reflect the change.
2. \ifthenelse{}{}{} conditionals. This is really handy when combined with the include files above. I have one set of source files that produce three completely different (but related) documents based on a few \def statements. For example, one's for internal use only and one's for wide release, but I only have to fix typos once.
3. Define (\def) statements. I keep version numbers and product names here. PHB says "We just changed the product name from "iCrap" to "eCrap". No problem. It's even easier than search-and-replace.
4. Comments. I comment the source files the my LaTeX documents. Most the time it's just snide remarks, but sometimes I leave useful comments behind.
%% The behavior described in the next paragraph
%% used to be a bug. Now we charge extra for it.
For a real-world example... (Score:5, Informative)
We're using Doxygen to generate HTML and man pages (!) for libstdc++-v3 [gnu.org], the standard C++ library that comes with g++ 3.x. Doxygen can also generate LaTeX, RTF/Word, and some other formats which I don't remember. If you have some additional nifty utilities installed, and tell Doxygen where they are, then Doxygen can automatically use them. Take a look at the inheritence and collaboration graphs on the pages I linked to: normally they're much plainer, and not color-coded. But I had dot(1) installed, which can generate pretty graphs.
Incidentally, LaTeX is much better than TeX when doing letters. There's a set of macros specifically for writing letters, and I use them all the time for, say, business letters.
.I'm told that it's not that hard to write a module for Doxygen to teach it how to create a new output format, if the half-dozen it knows about don't fit your needs.
Re:HTML, LaTeX, LyX., Word... (Score:3, Informative)
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.
Pod - Perl's Plain Old Documentation (Score:2, Informative)
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.
Re:PEBKAC (Score:2, Informative)
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
DocBook is my choice (Score:2, Informative)
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!
LaTeX vs WYSIWYG (Score:3, Informative)
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.
Ventura still scares me. (Score:2, Informative)
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.
Re:WordPerfect (Score:3, Informative)
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.
StarOffice 6 XML. *waves goodbye to Tex forever* (Score:3, Informative)
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.
Re:HTML, LaTeX, LyX., Word... (Score:2, Informative)
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.
I've been using LyX for a couple of years, and yes it does take some adjustment. The reason it's "non-intuitive" is because it tries to get you out of the "Word" mindset, which is that you have to do everything yourself. For writing papers and the like, you don't need the TAB key. Define the general layout of the document, and just type. That's the way it's supposed to work, and it works great for my purposes (school papers).
Apache Cocoon... (Score:3, Informative)
Re:Check out doxygen (Score:3, Informative)
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...
K.
Re:Word is horrible (Score:3, Informative)
Re:StarOffice 6 XML. *waves goodbye to Tex forever (Score:2, Informative)
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
Re:Ventura still scares me. (Score:2, Informative)
Ventura 8 is the same way: it took all that was so borked in Ventura 7, and fixed it. It's a joy to use now, and its capabilities are beyond belief.
You might want to check into Ventura 10 when it's released. Should be a cheap upgrade for you, and stands a good chance of blowing you away.
Noweb, Latex Re: Literate Programming (Score:2, Informative)
Re:Ten Reasons Why TeX/LaTeX is Better than Word (Score:2, Informative)
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 \]).
texinfo or docbook (Score:3, Informative)
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.
ConTeXt - a TeX macro set which accepts XML (Score:1, Informative)
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