Follow Slashdot blog updates by subscribing to our blog RSS feed


Forgot your password?

Writing Documentation 583

twms2h queries: "It is everybody's favorite task, the worst part of programming: writing the documentation. I have been charged with writing lots of documents, some smaller some larger, most of them documenting programs I wrote myself. In order to avoid the torture of fighting with Microsoft Word all the time (which crashes on me regularly) I am looking for an easy way to get printed and electronic (HTML/PDF) documents from as simple a source as possible. I have looked into several of the processing tools that are available on the net." Below is twms2h's take on a few of the documenting systems available. The preference is to keep things simple, editing ASCII files to produce high quality documentation. Are there other tools some of you know of that might prove to be better solutions?

"So far, I like aft, mostly because it is simple to use, and gives me nice result as HTML. Unfortunately HTML is not enough, since I also need a very good looking printable version.

There are alternatives like DocBook, which I could not get to work and udo (Page is German, get the translation from the fish) which I have not yet looked into very closely.

Then of course there is TeX and any number of WYSIWY-won't-G word processors. I haven't used TeX much, I only tried my luck in writing a few letters (and found out that it is not suitable for this). I went through hell when I wrote larger documents with various versions of MS Word and I am not really a fan of Star Office even though version 5.2 has not yet crashed on me (however 6.0 beta did). KWord, part of KOffice doesn't seem to be stable enough yet.

I would prefer a simple ASCII only format as the source for being converted to more complex formats anyway, especially since it could be easily put into CVS for version management (Anybody tried that with MS-Word documents? Don't!)

As all these projects show I am not the first one faced with this problem. I wonder what experiences Slashdot readers have had with these and other packages?"

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

Writing Documentation

Comments Filter:
  • try YODL (Score:5, Informative)

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

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

    by plalonde2 ( 527372 ) on Thursday January 10, 2002 @04:04PM (#2818627)
    Doxygen [] lets you mark up your source code pretty easily, and generates decent looking documents. You can use the same markup (and cross-reference facilities) in non-code documents processed at the same time.
  • by Anonymous Coward on Thursday January 10, 2002 @04:05PM (#2818635)
    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!
  • Doxygen (Score:3, Informative)

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

  • JavaDoc? (Score:5, Informative)

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

    And I don't think "documenting" is the worst part of programming. Its very sterotypical.
    I love design, and document while coding (usually in Java with Javadoc comments). Isn't that the way you are supposed to code?

    Especially in a team environment (even more "especially" with Open Source), documentation is critical. Having a good design documented well is how developers should interact with one another.

    Also check TogetherSoft. They have software that creates the UML while you code.
    I also like Together's identification of titles. A "Developer" is someone that designs, codes, and documents. A "Coder" is someone that codes. Which are you?
  • by seebs ( 15766 ) on Thursday January 10, 2002 @04:08PM (#2818668) Homepage
    I'm doing a bunch of documentation right now, and I *LOVE* docbook. I agree, it's a bit of a pain to set up; we started with openjade as a basis, and worked from there.

    Still, I love the format; it's clear, it's precise, and it's very well-suited to documentation.

    BTW, I'd like to point out that, if you think documentation is the worst part of programming, you're probably not writing very good documentation. Documentation can be a lot of fun. Think of it as a way to make sure that you won't have to do the maintenance later, because anyone will be able to do it based on your writing. :)
  • by uncadonna ( 85026 ) <> on Thursday January 10, 2002 @04:10PM (#2818691) Homepage Journal
    htmldoc is here [] .

    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)

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

    A fairly simple web application that allows a group to work on documentation together. Since it uses simple formatting rules, it's trivial to learn.

    It's the simplest way I know to let a workgroup develop a document.

    They have Wiki's that run on Perl, Python, Smalltalk, and PHP so it's easy to find one that you can modify to your heart's content.

    Most of the advanced wiki's have all types of bells and whistles (Eg: version control, authenicated users). Some of the wiki's can dump everything from the Wiki database to static HTML or TXT for further processing (which is nice when you actually want to publish).
  • by Anonymous Coward on Thursday January 10, 2002 @04:15PM (#2818737)
    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.
  • by RazzleFrog ( 537054 ) on Thursday January 10, 2002 @04:15PM (#2818740)
    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).
  • by PlazMan ( 40335 ) on Thursday January 10, 2002 @04:17PM (#2818757)
    I have to second that. DocBook can be a pain to get started with and learn, partially because it's soooo flexible and powerful. I probably spent a week getting all of the pieces together (editor, DTDs, Xalan, XSL, etc), but now I find it quite easy to churn out anything from a full reference manual to some simple man pages.

    I finally found Morphon's XML Editor [] and have been quite happy with it for editing DocBook documents (despite the fact that it's currently a beta version that will crash once in a while).
  • by Faramir ( 61801 ) on Thursday January 10, 2002 @04:19PM (#2818776) Homepage Journal

    A few notes from my experience:

    HTML: easy to write, easy to format. HTML TIDY [] 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!

  • by Anonymous Coward on Thursday January 10, 2002 @04:19PM (#2818783)
    You're absolutely right, documentation is THE most important part of a project. I think in-line documentation is the best for doing it.

    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.

  • by Anonymous Coward on Thursday January 10, 2002 @04:20PM (#2818786)
    just had to write an invoicing system that would generate invoices to a variety for formats and found tex/latex to be wildly useful for anything that needed to be burned on dead trees.

    in particular these resources

    • ng /latex_advanced/node1.html
    • ct ion=yes
    • kH ereFirst.html
    • La TeX.html#textpos
  • by jeffr ( 28143 ) on Thursday January 10, 2002 @04:20PM (#2818792)
    We're using the preloaded docbook on RH7.2
    and it works fine.

    Grab some emacs elisp files from sourceforge
    to round out the package and you are good to go
    with tag completion and font color locking
    in emacs.

    Docbook advantages:

    * no worries about formatting, just write content

    * can generate html, postscript, possibly wml, carved stone tablets, etc.

    * can be parsed by freely available xml parsers
    to intelligently extract, say, all authors, all section titles. This could be done with raw
    perl, but why rewrite an xml parser when so
    many already exist?

    * documents can be easily stored in an OODB,
    using an xml->object marshaller, if you are
    into that sort of thing. This allows
    any number of documents to be subject to
    the full power of the database querying
    and indexing.

    Latex (tex) is great, and I've used it for 20 years,
    but its definitely not the same thing as docbook.

    allows - encourages actually - one to think
    about appearance while writing the document.
    And you do get great looking output.
    But you sacrifice everything that docbook/xml
    offers in terms of document parsing for other
  • FOP (Score:1, Informative)

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

    It's a bit of a pain to set up, but once it's going, it's great (much like most of Linux, I find ;-) ). I use Jade -- openjade seems to be slower, and I couldn't see any advantage of openjade over Jade.

    My only complaint about docbook is that it (currently) doesn't do math too well -- I use Walsh's stylesheets, and they don't seem to grok MathML yet -- so I have to stick with LaTeX for some things still. Oh, and its table support doesn't seem to be complete when using the TeX backend, so things may come out in unexpected ways.
  • by Arandir ( 19206 ) on Thursday January 10, 2002 @04:29PM (#2818888) Homepage Journal
    It's not that big of a pain to set up if you have a decent distro that's done the work already. I use FreeBSD, and getting a DocBook environment set up is trivial. It's equally simple under Debian. Slackware has a single package in contribs. Etc.

    If your distro doesn't have a docbook package then it can be a major hassle building and setting it up from scratch.
  • by gfilion ( 80497 ) on Thursday January 10, 2002 @04:31PM (#2818908) Homepage

    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: []

    General docbook information: []

    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.

  • by printman ( 54032 ) on Thursday January 10, 2002 @04:36PM (#2818959) Homepage
    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.
  • Re:PEBKAC (Score:2, Informative)

    by Carpathius ( 215767 ) on Thursday January 10, 2002 @04:52PM (#2819080)
    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.

  • Framemaker (Score:1, Informative)

    by Anonymous Coward on Thursday January 10, 2002 @04:56PM (#2819110)
    Everywhere I go, the doc writers are either using Framemaker, or switching from Word to Framemaker.

    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). ml
  • by klund ( 53347 ) on Thursday January 10, 2002 @04:58PM (#2819127)
    You can make nice pdf and print version. Yes it takes some time to get use to and most WYSIWYG people don't like it but it rocks in CVS.

    In addition to producing HTML and PDF with latex2html and pdflatex, there are some other features in TeX/LaTeX that appeal to code monkeys like me.

    1. Real include files. For example, you can write a mission statement page that gets included in the front of all your documents. When the mission statement changes, you only have to update it in one place, and all your documents reflect the change.

    2. \ifthenelse{}{}{} conditionals. This is really handy when combined with the include files above. I have one set of source files that produce three completely different (but related) documents based on a few \def statements. For example, one's for internal use only and one's for wide release, but I only have to fix typos once.

    3. Define (\def) statements. I keep version numbers and product names here. PHB says "We just changed the product name from "iCrap" to "eCrap". No problem. It's even easier than search-and-replace.

    4. Comments. I comment the source files the my LaTeX documents. Most the time it's just snide remarks, but sometimes I leave useful comments behind.

    %% The behavior described in the next paragraph
    %% used to be a bug. Now we charge extra for it.
  • by devphil ( 51341 ) on Thursday January 10, 2002 @05:00PM (#2819151) Homepage

    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.

  • by fperez ( 99430 ) on Thursday January 10, 2002 @05:01PM (#2819166)
    I beg to differ on the LyX issue. I (and many others) find it unbelievably useful, as an easy to use front end to the underlying raw power of latex and friends.

    I personally use LyX not only for technical stuff (physics) but also for software documentation. The manual for my most recent project IPython [] 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 [] 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.

  • by Big Stick ( 318410 ) on Thursday January 10, 2002 @05:04PM (#2819193) Homepage
    Though I initially started using Perl's Pod to embed documentation in my programs, I have found it very useful in other non-Perlish circumstances.

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

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

    Something to consider, especially if your shop has Perl installed already.
  • Re:PEBKAC (Score:2, Informative)

    by Anonymous Coward on Thursday January 10, 2002 @05:05PM (#2819205)
    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
  • DocBook is my choice (Score:2, Informative)

    by slagdogg ( 549983 ) on Thursday January 10, 2002 @05:14PM (#2819328)

    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)

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

    WYSIWYG is also a pain in many ways:

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

    LaTeX does have some disadvantages, however:

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

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

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

  • by Rikardon ( 116190 ) on Thursday January 10, 2002 @05:30PM (#2819501)
    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.
  • Re:WordPerfect (Score:3, Informative)

    by istartedi ( 132515 ) on Thursday January 10, 2002 @05:31PM (#2819502) Journal

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

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

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

  • by Nailer ( 69468 ) on Thursday January 10, 2002 @05:41PM (#2819551)
    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.


    * 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.
  • by PlaysWithMatches ( 531546 ) on Thursday January 10, 2002 @06:10PM (#2819794) Homepage

    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)

    by graveyhead ( 210996 ) <fletch AT fletchtronics DOT net> on Thursday January 10, 2002 @06:28PM (#2819912)
    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.
  • Re:Check out doxygen (Score:3, Informative)

    by Karellen ( 104380 ) on Thursday January 10, 2002 @06:37PM (#2819972) Homepage
    Doxygen is great for producing API references with source code cross-references, if that's all the documentation you need. I've no problems with it there. It rules.

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

    I'd take a closer look at Docbook and the fairly large set of untilities that exist for converting it to HTML, TeX, man, texinfo, etc... Check

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

  • Re:Word is horrible (Score:3, Informative)

    by RadioheadKid ( 461411 ) on Thursday January 10, 2002 @06:44PM (#2820014)
    Two points: you can turn all that stuff off that you are complaining about and usually that green line is pretty valid, its the user that doesn't understand the problem, like passive voice.
  • by PONA-Boy ( 159659 ) on Thursday January 10, 2002 @06:44PM (#2820017)
    *SHHESH* !!!!

    FINALLY, a post which really talks to the question this thread was started for!!!

    Damn that .sig was right: "Putting a lameness filter on Slashdot is like putting a shit filter on your ass!!!"

    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.

    King of the Who?.sig
  • by FFFish ( 7567 ) on Thursday January 10, 2002 @07:09PM (#2820193) Homepage
    Ventura 7 was an unmitigated disaster. Typical of Corel: they can fuck things up so royally, yet turn around and release pure heaven. CorelDraw 10 seems to be one of those cases, if the bits I've heard are true: the release sucks shit through a straw, while the service release patches have made it well worth using.

    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. :-)
  • by buzz_mccool ( 549976 ) on Thursday January 10, 2002 @08:01PM (#2820495)
    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 []
  • by matsukio ( 27212 ) on Thursday January 10, 2002 @08:32PM (#2820671)
    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 \]).
  • texinfo or docbook (Score:3, Informative)

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

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

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

  • by Anonymous Coward on Friday January 11, 2002 @05:59AM (#2822324)

    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 :(. Use PDF :)

To write good code is a worthy challenge, and a source of civilized delight. -- stolen and paraphrased from William Safire