Writing Documentation

Out of curiousity by Sheepdot · 2002-01-10 08:01 · Score: 5, Insightful

Just out of curiousity, what are you writing documentation for? I myself would approach the problem according to what kind of software it was, and who the intended audience was.

A point about M$ word by Anonymous Coward · 2002-01-10 08:02 · Score: 5, Insightful

It will do versioning. See the menu file/versions

Re:A point about M$ word by Florian+Weimer · 2002-01-10 10:16 · Score: 2

And Word versioning is compatible with which configuration management systems?

try YODL by CommanderTaco · 2002-01-10 08:03 · Score: 5, Informative

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/

LYX by ocelotbob · 2002-01-10 08:03 · Score: 5, Informative

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

Check out doxygen by plalonde2 · 2002-01-10 08:04 · Score: 5, Informative

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.

Re:Check out doxygen by WasterDave · 2002-01-10 09:57 · Score: 2

Me too! I've used doxygen in real world projects, and managed to convert my source with scratty "when I feel like it" comments over to lovely shiny HTML docs that nobody will ever look at in, ohhh, a day? About that.

Dead easy and doesn't interfere with writing code.

Dave

--
I write a blog now, you should be afraid.
Re:Check out doxygen by Karellen · 2002-01-10 10:37 · Score: 3, Informative

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 http://www.oasis-open.org/docbook/

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

K.

--
Why doesn't the gene pool have a life guard?

what kind of documentation? by SirSlud · 2002-01-10 08:04 · Score: 2

full disclosure: I hate documentation (unless its in other people's code ;) and I've been able to luck out in working at places where we need the code written so fast that documentation is an afterthought.

what about javadoc (is it still called that)? it's good for turning well-formatted function summaries into browsable HTML ....

Are we talking API documentation here, or real-world english implementation documentation? if you're looking for just a good ASCII editor, straight off, ultraedit is easily my favorite, but if you are looking for stuff to skim your source and rip out inline documentation, obviously, thats not what you're looking for. but javadoc might be?

--
"Old man yells at systemd"

Documentation is not evil! by deblau · 2002-01-10 08:06 · Score: 5, Insightful

In fact, in most projects, documentation is more important than the code itself! This rule holds for all programs you intend for someone other than yourself to run (or, heaven forbid, debug later). My general rule of thumb for doing projects is:

Do feature reqs (10%)
Do design spec / unit spec (30%)
Do documentation (30%)
Write code (15%)
Beta-test / debug (15%)

Notice that design and documentation take up more than half the time on the project. Implementing the code becomes very easy with good, fleshed-out design and documentation.

As for solving your problem, I generally write documentation in-code using one style of comments and line-by-line comments using another style. Then forming docs from the code is easy: write a little perl script to extract the block comments, and format as you like.

--
This post expresses my opinion, not that of my employer. And yes, IAAL.

Re:Documentation is not evil! by FortKnox · 2002-01-10 08:38 · Score: 5, Insightful

but you write the documentation as comments to the code you haven't written yet

ABSOLUTELY!
You should design every object and every function (down to what the functions input and return are) before coding everything. You should be able to write comments on the function (on the function, not in. Even having stubs for the function) before it is written. Then, you know EXACTLY what the function needs to do when you code it. You even have a nice reference doc for your teammates (if you use javadoc with java).

I've taken this approach MANY times, and I can't tell you how SIMPLE it is to code with this. Its like a homework assignment "Write a function foo, that takes two integers, adds them, and returns it as a real". The code practically writes itself. And the project manager usually doesn't have any trouble tying all the objects together.

I might as well add that this is a great technique to make open source work well and fast.

--
Good quote, too many chars. Seriously, the slashdot 120 char limit sucks!
Re:Documentation is not evil! by MaxwellStreet · 2002-01-10 08:50 · Score: 2

It sounds excessive, until you think about it.

If you've figured out exactly what every button and form and screen looks like, how they fit together, and how the program will work before you've written a line of code, chances are the coding will go very smoothly.

Prototype the GUI to create the screen shots, and write the documentation. It'll force you to think the entire application through before you start building.

This isn't the first time I've heard of this methodology, and it's not as crazy as it sounds.

In a way, it's kind of like UML - writing all those nine different kinds of diagrams before you start coding - by the time you get to the code, it's all pretty much filling in the blanks - all figured out.

UML is the better way to go, in my experience - you architect the system in advance on a much deeper level than writing user documentation.
Re:Documentation is not evil! by Dominic_Mazzoni · 2002-01-10 09:32 · Score: 2

Sure, there are lots of circumstances where you know what you're trying to write and you can design the whole program before writing a line of code.

But that doesn't work at all when you're trying to come up with a new algorithm, experiment with different user interfaces, extend an existing program to do more things, or any one of a number of tasks where you have to "get your feet wet" coding it for a while before you can clearly see the design.

I'm a big fan of rapid prototyping. In my opinion, there's no better way to figure out the best way to program something than to start writing some code.

This does NOT mean that you shouldn't go back and document the code (both with inline comments and external documentation), I'm just trying to argue that it's easy to fall into the trap of overdesigning a program initially, before you really understand the coding tradeoffs you might have to make. Also, there's nothing worse than a fully documented program where the documentation is wrong! I've seen too many cases where the documentation says one thing, but the code does something different because later the programmer realized she needed another argument to a function, and threw it in without fixing the docs.

I guess in my opinion it's not a question of "document, then code", or "code, then document". I have to go back and forth between the two all the time. Initially I write out a short design just so I'm clear what the main goal of the program is. Then I start writing some code. Then I go back and start documenting the parts I coded well, and redesigning the parts I need to redo, in greater detail, and so on.
Re:Documentation is not evil! by coldtone · 2002-01-10 09:53 · Score: 2, Interesting

I had enough of this argument. Its simply crap, and is always written by non programmers, or by programmers who are not responsible for delivering the real product.

Lets look at how a house is built, is all of the time spent in spec and design. Do they write a document outlining how the tub will be installed in the top floor bedroom?
No, they provided a picture of what they want. (Detailed mind you, but still is just a picture.) From that the construction company builds it. The builders never get a step by step checklist.

But when it comes down to documentation (At my company at least) They want everything, what classes are there, what methods, how the code will be written, yada, yada, yada.

While this information might be interesting, it is not useful! It means nothing to the end product, or to even maintenance of the code. If you have done any type of maintenance to code you know the only way to do it is to read the code!

As long as you have a clear picture of what to build you can create the product, and then SELL it! Excessive documentation only slows the development process and adds to a company's bureaucracy.
Re:Documentation is not evil! by Anonymous+Brave+Guy · 2002-01-10 10:06 · Score: 5, Insightful

You should design every object and every function (down to what the functions input and return are) before coding everything.

Sorry, gotta disagree with that. The place of design docs is not to mandate the details, like the exact function inputs and outputs. The place of the design docs is to paint the big picture, perhaps down to assigning the responsibilities to the major building blocks of your code (principle functions, classes, etc.).

Requirements change. This is a fact of life. No real project I've seen since I was a student had requirements that stayed fixed, or even close to fixed, during a whole development cycle. As a result, your design must change.

Furthermore, your initial design will probably be flawed in many ways you don't anticipate until you start trying to implement it. Unless you're copying an algorithm out of a textbook or a design you've used before, you'll be lucky to be even close to your final design on your first pass. As a result, your design will evolve.

If you attempt to record every little detail in the design docs, two things will happen. First, you will cripple the pace of development, as you spend more time updating paperwork than you spend developing. Secondly, your design docs will rapidly become out of date, and hence useless anyway.

The correct place for comments about the details is in the code. This is where you should record the exact input/output parameters of a function, the behaviour in error cases or the meaning of a little helper function. A combination of descriptive names for things and judicious use of comments will do far more for you than a 500 page printout of last month's code base.

Making your code its own detailed documentation allows for fast prototyping -- often the quickest way to find a good basic design -- and for ready modifications as the design evolves. This leaves design docs free to do what they should: recording the overall design.

Welcome to the 21st century, where the waterfall model dried up.

--
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
Re:Documentation is not evil! by cfulmer · 2002-01-10 13:37 · Score: 2

I'm not sure if this was tongue-in-cheek or not.

One of the problems with this method is that it assumes that you know in advance how everything works -- all too often, this isn't the case, and so you end up iterating over your design. For some projects, it may work well, but for others.... ick.

On the other hand, you definately want to have a basic plan-of-attack (ie "this is how I think it's going to work, more-or-less. Here are the key abstractions and here's how I plan to manipulate them") in a format that other people can look at and review -- the point here is to allow other people to catch problems in your approach *before* you commit all the time putting it in code.

As far as how to write documents -- I do as much documentation in *emacs* as I possibly can. (*Gasp* they say). I draw out diagrams long-hand. Once all that's done, I put it into the tool (Adobe FrameMaker in our case). The point here is that it prevents me from being distracted by formatting (ie "how it looks") and concentrate on content ("what it says.")
Re:Documentation is not evil! by Kiwi · 2002-01-10 14:29 · Score: 2

But when it comes down to documentation (At my company at least) They want everything, what classes are there, what methods, how the code will be written, yada, yada, yada.
And I do not blame them. I have been on more than one project where I was put in the position of having to decrypt over 100 pages of poorly written code, without a single comment in the entire code. They are trying to insure the code is maintainable, because a lot of programmers do not write maintainable code.
- Sam

--
The secret to enjoying Slashdot is to realize that it should not be taken too seriously.
Re:Documentation is not evil! by dubl-u · 2002-01-10 18:44 · Score: 2
I had enough of this argument. Its simply crap, and is always written by non programmers, or by programmers who are not responsible for delivering the real product.

Hi. I'm a programmer. I've been programming for money since I was 16. I deliver.

I agree that excessive documentation is bad. And that many companies have official policies that, if actually followed, would result in excessive documentation. Know why they have those policies? Because most programmers don't write enough documentation.

(That's ok by me; I bill by the hour, and I charge extra when dealing with a steaming pile undocumented code. And the hours rack up quickly when I have to step through code in the debugger just to figure out what the hell it does. Attitudes like yours have made me hundreds of thousands of dollars over the years.)

If you have done any type of maintenance to code you know the only way to do it is to read the code!

This sounds persuasive, but it's several different kinds of bullshit rolled together. Yes, you do have to read the code to do maintenance. But good docs speed that process up immensely.

Personally, I find that projects with good basic docs generally have good design behind them. Projects that have no docs whatsoever usually have designs that make train wrecks look organized.

-----

When I do maintenance, I like to see five different things:
1. A few pages of broad overview docs. Something that gives the big picture in a few pages can save me days of work trying to figure out how several thousands classes go together. Note that a five-hundred page overview document is generally worse than no documentation at all.
2. Single-paragraph descriptions for packages and classes. A little basic info plus known caveats is optimal.
3. One-sentence method descriptions for those methods whose names don't make it completely obvious, and
4. Beautiful, readable code, where names are apropos, coding conventions are followed, flow control is clear, and no method/function is longer than fifty or so lines, and
5. Unit tests, so that I can know what the code is supposed to do, not what you happened to make it do.
Which is basically the kind of code that followers of XP produce. So if you're already doing that, swell; tell your managers to get lost if they demand you document every setName method. But most people don't. And most of the coders I see bitching about how they don't have time to document are the ones who write code that really, really needs documentation.
Re:Documentation is not evil! by Syberghost · 2002-01-11 08:30 · Score: 2

Lets look at how a house is built, is all of the time spent in spec and design. Do they write a document outlining how the tub will be installed in the top floor bedroom?
No, they provided a picture of what they want. (Detailed mind you, but still is just a picture.) From that the construction company builds it. The builders never get a step by step checklist.

That's how mine was built. And it came out great, as a result. Immediately appraised for more than I paid for it.

And their results are predictable and repeatable. Very few of their houses don't turn out great.
Re:Documentation is not evil! by Anonymous+Brave+Guy · 2002-01-14 07:10 · Score: 2

Thsi is where design patterns come in, my dear. Reusble design is a good thing.

However, most of the value in design patterns is in the "fine-tuning" stage of your design process, as you've got the basics worked out and you're trying to tidy things up. While design patterns certainly can suggest an initial plan as well, IME it's a bad idea to aim for a particular design pattern as a goal in its own right.

Also, the liberal use of analysis patters will help you avoid making those flawed design decisions.

Sure, and next week my client will give me requirements that are at least roughly what the finished ones will be, right at the start of the project. ;-)

Welcome to the 21st century, where reuse rules.

(Code) reuse is largely a myth, propagated by theoreticians and PHBs with little real experience. (Design) reuse, as typified by successful design patterns, is a more useful concept, but as noted above, it really comes into its own when you're tidying up and -- dare I say it? -- documenting the design you've chosen, rather than in forming your initial design. The trick, of course, is to make sure that whatever design you come up with is easily maintainable and responsive to changing requirements, and design patterns are one tool in the armoury for this purpose.

Welcome to the 21st century, where the ability to adapt to rapidly changing requirements is the difference between a thriving business and a dead one...

--
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.

texinfo by phr2 · 2002-01-10 08:07 · Score: 3, Interesting

Call me a throwback or GNU-head but I like texinfo. The stuff you type reflects the structure of your document, it's plain ascii (easy to edit with emacs or your favorite editor), and compiles to online docs, html, or printed docs using TeX. It does make some impositions on your writing style but I find the texinfo formatting commands much easier to deal with than (say) html tags. I use it even when I want plain ascii docs. I just don't put in any "node" commands. Then I run the texinfo doc
through the emacs formatter and use the formatted ascii output.

So, it's old and limited but still my favorite.

Re:texinfo by Jason+Earl · 2002-01-10 09:18 · Score: 3, Interesting

Texinfo isn't at all limited. In fact, it rocks. It has most of the advantages of LaTeX, it generates beautiful looking html, cross-referenced pdfs, gorgeous postscript, and info files to boot. And the Texinfo-mode for Emacs does most of the tricky bits for you. It builds the menus, makes sure the links all go to the right places, etc. etc.
For computer documentation I personally prefer it over LaTeX (and that's saying a lot).

Doxygen by dan+g · 2002-01-10 08:07 · Score: 3, Informative

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.

JavaDoc? by FortKnox · 2002-01-10 08:08 · Score: 5, Informative

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!

Docbook, docbook, docbook. by seebs · 2002-01-10 08:08 · Score: 5, Informative

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/

Re:Docbook, docbook, docbook. by PlazMan · 2002-01-10 08:17 · Score: 4, Informative

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).
Re:Docbook, docbook, docbook. by hackerhue · 2002-01-10 08:24 · Score: 4, Informative

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.

--
To get something done, a committee should consist of no more than three persons, two of them absent.
Re:Docbook, docbook, docbook. by Arandir · 2002-01-10 08:29 · Score: 2, Informative

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.

--
A Government Is a Body of People, Usually Notably Ungoverned
Re:Docbook, docbook, docbook. by seebs · 2002-01-10 11:10 · Score: 2

A good point. I was doing the first round of getting it running under BSD/OS; it won't be nearly that much work next time. :) We also needed a few supporting tools, such as jadetex.

--
My blog: http://www.seebs.net/log/ --- My iPhone/iPad app: http://www.seebs.net/seebsfrac/

Re:PEBKAC by mcelrath · 2002-01-10 08:08 · Score: 5, Insightful

Uh, wrong.

If an application crashes, it's the developer's fault. Period. End of story. It is NEVER the user's fault.

To answer the article's question. I recommend LaTeX, LyX, latex2html (comes with LaTeX), and dvipdf (comes with ghostscript).

--Bob

--
1^2=1; (-1)^2=1; 1^2=(-1)^2; 1=-1; 1=0.

versioning by motherfuckin_spork · 2002-01-10 08:08 · Score: 2, Interesting

versioning is a crucial element to not just documentation, but to methodology as well, in particular with the field I am in, being the pharmaceutical industry. You must be able to see how things like analytic methods have progressed, specifically when moving from development to production. I can easily see parallels between this and programming.

--
Nope, not me, I must be someone else...

Possible solution by Fembot · 2002-01-10 08:09 · Score: 2, Insightful

HTMLDOC appears to serve your purpouse. It appears only windows binaries are avalible however but the sourcecode is avalible under the GPL

convert simple html to pdf by uncadonna · 2002-01-10 08:10 · Score: 2, Informative

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.

----

--
mt

Re:convert simple html to pdf by printman · 2002-01-10 08:36 · Score: 3, Informative

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.

LaTeX seemed the simplest way by StormC · 2002-01-10 08:11 · Score: 5, Insightful

I've been writing documentation for a little while now and LaTeX always seemed the best way to solve the problem. 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.

Re:LaTeX seemed the simplest way by klund · 2002-01-10 08:58 · Score: 5, Informative

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?
Re:LaTeX seemed the simplest way by klund · 2002-01-10 12:35 · Score: 2

I have one contention with latex2html--it does not follow included files. I have my document broken down to multiple files, each to a chapter. And in the main tex file, I've added the \include{chapter1} etc. where I want the chapters to appear. When I try to latex2html the main tex file, it burps and spits out an error saying it doesn't like included files.

Don't use \include{}. Use \input{} instead.

\include{} is a holdover from when LaTeXing a document would take a *long* time and use valuable and expensive CPU time on your timesharing account. With a fast, single-user desktop machine, there is no reason to use the ugly \include{} and \includeonly{} hacks.

latex2html works just fine with \input{}.

--
My word processor was written by Stanford Professor Donald Knuth. Who wrote yours?

Another Great Benefit of Java by Enonu · 2002-01-10 08:11 · Score: 3, Insightful

Javadocs are one of the best resource I have at my disposal for documenting my programs and reading the documentation of others. It's a wonder something like this wasn't in mind for every major language ever conceived. Never seen them before in action? Here's a link to the docs on Sun's website. Upper left corner is the specific package you want (like namespaces). The default view is all classes. Lower left is the classes for the current package chosen. The main frame contains the specfic documentation for that class. Everything is hyperlinked to everything else, so getting from one relevant document to another is cake.

I believe there are other systems that implement a Javadoc like utility for other language. Do a google for "Javadoc for C++" for example and plent of links show up.

Wiki by Big+Sean+O · 2002-01-10 08:11 · Score: 3, Informative

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.

javadoc works well for Java code by AirHog · 2002-01-10 08:12 · Score: 2, Insightful

The Java Development Kit from Sun comes with the javadoc tool. It extracts comments from specific locations in your source (/** */ -style comments) and produces HTML documentation. It has a plug-in architecture for support of other output formats. Sun provides plug-ins for FrameMaker and a couple of other formats, or you can write your own.

I have automated its use on several projects. Make a cron job that:

Gets a copy of the latest sources from CVS
Runs javadoc against the fresh sources

Each morning you'll have up-to-date documentation.

-Andy

gobeProductive 3.0 by tswinzig · 2002-01-10 08:14 · Score: 2

I'm using gobeProductive 3.0.2 on Windows (they have or will have a Linux version). It's like a light-weight replacement for MS Office, done by the same team that did Claris Works for the Mac.

The word processor is very easy to use, and can save in the gobeProductive format, as well as Word, HTML, PDF, RTF, and plain text.

The office suite also has spreadsheet, graphics, image processing, and presentation software.

http://www.gobe.com/

--

"And like that ... he's gone."

Re:TeX? by elmegil · 2002-01-10 08:14 · Score: 2

And while TeX of various flavors is not WYSIWYG, there *are* whizzy-wig editors that save to TeX flavors. I haven't tried using one in ages, so I can't make any recommendations, but if editing macros is an impediment to you, you should check it out. TeX results are excellent for publishing as a book as well as generating HTML etc.

--
7 November 2006: The day Americans realized corruption and incompetence weren't addressing 11 September 2001

Re:PEBKAC by Kallahar · 2002-01-10 08:18 · Score: 3, Interesting

Uh, wrong.

Sometimes it is the hardware, malicious programs, other programs, or the operating system too.

You're right that it isn't the user's fault, but the blame can fall on any of the developers of any running software or hardware on the system, not just the application's developer.

Or, to sum it up, blame microsoft since they do it all :)

HTML, LaTeX, LyX., Word... by Faramir · 2002-01-10 08:19 · Score: 5, Informative

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!

Re:HTML, LaTeX, LyX., Word... by hereticmessiah · 2002-01-10 09:01 · Score: 2, Insightful

If you had problems with LyX, it's because you were treating it as a Word Processor, which it isn't. If it's counterintuitive, that's why. this comment explains things better than I could. The worst thing about LyX is that XForms is ugly and clunky, but you get over that.
Did you even think of reading the manuals? If I was using a program that uses a paradigm I wasn't used to, I'd read the manual. I mean, you wouldn't expect a functional language like O'Caml to work the same way as an imperitive language like C, would you? It's the same sort of thing, in a way.

--
I don't like trolls and mod against me if you like, but I'd prefer if you'd reply.
Re:HTML, LaTeX, LyX., Word... by fperez · 2002-01-10 09:01 · Score: 3, Informative

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.
Re:HTML, LaTeX, LyX., Word... by PlaysWithMatches · 2002-01-10 10:10 · 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).

--

Mozilla's a nice operating system, but it needs a better browser.
Re:HTML, LaTeX, LyX., Word... by Syberghost · 2002-01-11 08:55 · Score: 2

The worst thing about LyX is that XForms is ugly and clunky, but you get over that.

They're working to fix that by making it GUI-independant.

I believe there is a Gnome frontend already, but I have never used it.

WordPerfect by mkoenecke · 2002-01-10 08:19 · Score: 5, Interesting

Remember WordPerfect? Version 9, SP4, is rock solid stable and does not suffer from Word's inability to handle long documents. (The primary culprit: Word's continuous repagination and reformatting, required by the document structure.) Versioning is supported, and WordPerfect, unlike Word, has the native ability to generate PDF files. Version 10, SP2 does even better, formatting hyperlinks automatically in PDF files, but I won't recommend it yet because there's a nasty interaction bug between it and Mozilla.

Not to mention WordPerfect's ultimate advantage over Word: Reveal Codes. In Word, any fouled-up formatting can only be fixed by *different* formatting. In WordPerfect, you can *remove* offending code. And it's more customizable, doing things the way you want them done, not the way Microsoft dictates. I could go on about dozens of other advantages, too.

Oh yeah, there are Linux versions available too (albeit using Wine).

Frankly, I'm amazed that any person with technical knowledge and expertise would use Word by choice.

--
TANSTAAFL

Re:WordPerfect by istartedi · 2002-01-10 09:31 · 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.

--
For all intensive purposes, "whom" is no longer a word. That begs the question, "who cares"?
Re:WordPerfect by Syberghost · 2002-01-11 09:01 · Score: 2

You know, if I had a car that occasionally turned left and died when I turned the wheel to the right, I wouldn't sigh and try again, I'd sell the goddamn thing to a scrapyard and use a car that didn't do that.

Hence why I don't use Word or WordPerfect except when I'm required to by my employer; I use Lyx.

Diff'ing by Da+VinMan · 2002-01-10 08:20 · Score: 2

And, so how are you able to run a diff of some sort against your document? Unless your tools supports this (MS Word does BTW), then you are SOL. I think it's too much to ask the version management software to do that.

Now, if you're using pure ASCII files to do your document, you can easily diff the file and inspect it using many other common stream tools (e.g. grep, perl, wc, uniq, etc.) for many purposes.

--
Please mod this post only if you think others should/n't read this. I have enough ego^H^H^Hkarma. Thanks!

Re:And after you're done? by RazzleFrog · 2002-01-10 08:20 · Score: 2, Funny

When all of your code is documented, you'll become expandable

Is that because you'll sit back and eat lots of twinkies? I think the word you are looking for is expendable.

docbook does work, and works well by jeffr · 2002-01-10 08:20 · Score: 5, Informative

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.

No question - use LaTeX by jelson · 2002-01-10 08:22 · Score: 5, Insightful

I grappled with exactly this problem for years. I wanted something that would give me superb quality Postscript/PDF, good HTML, and at least passable ASCII text. (In 1994, it was still important to distribute ASCII documentation; not everyone had a web browser.)

I went back and forth with all sorts of things: SGML based solutions, a few more "proprietary" utilities, etc. Finally, the latex-to-other-format conversion tools got to be good enough that I could use LaTeX as my primary format.

My most recent documentation is for FUSD, a Linux framework for user-space devices. The original documentation source is LaTeX. Simply running LaTeX gives you DVI, which you can convert into publication quality Postscript. Using pdflatex (NOT ps2pdf), you can also create very high quality PDF, which includes a real PDF table of contents, cross-references, and URL links. Finally, using latex2html, you can create almost native-quality HTML documentation. And, if you really need ASCII, you can get a reasonable rendering by running lynx (in its ASCII-dump mode) over the HTML.

latex2html comes with special LaTeX macros that let you specify hyperlinks inside your document. They are rendered as real hyperlinks in HTML, and footnotes in the printed versions.

Migrating from LaTeX to DocBook by 4of12 · 2002-01-10 08:23 · Score: 2

I agree wholeheartedly with your desire to keep the documentation in ASCII text instead of some binary proprietary format.

I have TeX files from over 10 years ago that

were produced on different hardware than I'm running now
were produced on a different operating system than I'm running now
still can be run through TeX
still produce unmatched quality of output, particularly for mathematics
can be quickly and easily searched with tools like grep
are friendly to the CVS version control system

and all for free!

That said, I'm looking into using DocBook in the near future, particularly after seeing how well it's been working for the Linux Documentation Project.

XML is definitely a good way to go; I'm just not sure if the latest DTD's do a sufficiently nice job on mathematics (via MathML) and on graphics (looking for SVG, not just images).

--
"Provided by the management for your protection."

A few... by Matthew+Weigel · 2002-01-10 08:25 · Score: 2

1. Take a look at literate programming tools, like noweb or doc++ (language specific).

Given the broad nature of you query it's not clear what is most appropriate for you; but literate programming might be what you need.

2. Framemaker. I've never used it myself, but I have known people who did all of their word processing in it. Pretty output, can do web output too, and definitely intended for larger documents.

3. Look at [La]TeX again. Seriously. Some of the stuff you need may not be easily provided, but I don't know. Get the book on LaTeX and see if that doesn't handle your previous problems.

--
--Matthew

Not to be the obvious, but upgrade to Win2k or XP by cybrthng · 2002-01-10 08:25 · Score: 2, Insightful

I use word, Visio, Toad (oracle), eXceed (x), Lotus Notes, Netscape, Jinitiator (11i client), and SecureCRT all day long and have no problems.

95,98, NT 4 and 2ksp1 crashed, but i have yet to have a random crash under Win2kSP2 or XP.

Have you looked into reasons of why our PC crashes? I'm constantly building Visio diagrams, documenting schema's, editing 500 page documents full of 20-30 meg schema diagrams and at the same time telneted into several servers, and connected to an application server running on Solaris through exceed and still running Lotus notes and whatnot..

must be buying some sour computers man.

Hello, i just have my laptop go into sleep mode, open it up when i get hope and pick right up (with the exception of telnet sessions).

Why change your whole application suite for what could be an obvious hardware or application problem. My pc quit crashing on my almost 2 years ago and over the last year hasn't crashed unless *I* did something wrong. (like say Yes to a message warning me my VPN driver wasn't certified for XP, but thankfully after rebooting it rolled back to a working config very nicely).

oh well. your loss if you can't figure out what is wrong and blame it on blue screen o'death

Re:PEBKAC by viking099 · 2002-01-10 08:25 · Score: 3, Interesting

I have to disagree. The developer does have the most important part in making something not crash, but you can NEVER take into account what a user can/will do. For example, if a user decides that they want to use MS Word as their file manager, and it crashes, is that the developers fault?
I would edit your statement to say something more along the lines of:
If an application crashes while being used as it was intended, it's the developer's fault.

Re:PEBKAC by ortholattice · 2002-01-10 08:27 · Score: 2

I use pdflatex to generate PDF files directly, instead of latex -> dvipdf. It comes with the latex package. I recall there were some problems with some documents with the two step process that went away with pdflatex, but it's been a long time since I used dvipdf and I can't remember the details. I've never had a problem with pdflatex.

Re:PEBKAC by pmz · 2002-01-10 08:28 · Score: 2, Insightful

Quite simply, no two MS Windows systems behave the same. The configuration control in Windows is so poor that MS Word might work great on one computer and never work well on another. If a person likes to install a variety of software from a variety of sources...well, then, pretty much all bets are off. In general, the less sofware installed on a Windows system, the better. This isn't an argument for installing only Microsoft software; this is an argument that Microsoft produced an OS that can't be managed well.

...as for the article, LaTeX is always good (even for writing letters), Doxygen with C++ seems pretty good, too, but, as always, plain text is best.

--
Healthcare article at Kuro5hin

POD by Genady · 2002-01-10 08:30 · Score: 2

Really. Most of the programming I do is in PERL, and I had the same problem. There are TONS of ways to convert POD to other formats. Hell The PERL Cookbook was written in POD with some TROFF markup.

--

What if it is just turtles all the way down?

obvious joke, sorry by Graspee_Leemoor · 2002-01-10 08:30 · Score: 3, Funny

"I have been charged with writing lots of documents"

...In the trial of the /. submitter vs the hacker community the defendant was found guilty of writing documentation. He also asked for several charges of using meaningful variable names be taken into consideration.

graspee

Use DocBook and document as you code by UsonianAutomatic · 2002-01-10 08:31 · Score: 3, Insightful

Or document even before you start coding, as someone else already mentioned; I've found that starting documentation early on accomplishes two things:

it helps the planning process immensely by forcing you to really think about what your code is going to be doing, and
it ensures that the documentation end of the project doesn't get short shrift; once the code is done it's too easy to gloss over the documentation when the next project is breathing down your neck.

DocBook easy to author with... the pain in the neck part is setting up a processing environment with Jade/OpenJade/DSSSL, but it's well worth it. It's also possible to use XSL/XSLT to process DocBook XML, but I don't know how involved the setup is. YMMV.

Docbook explained by KDE's team by gfilion · 2002-01-10 08:31 · Score: 2, Informative

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.

LEO, Donald Knuth & Literate Programming by Belly+of+the+Beast · 2002-01-10 08:32 · Score: 2, Interesting

Leo is a programmer's editor that represents a noweb or CWEB (literate) program as an outline. The combination of literate programming and outlining creates a powerful and enjoyable new way of programming.

Donald Knuth. "Literate Programming (1984)" in Literate Programming. CSLI, 1992, pg. 99.
I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming." Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other

HappyDoc by Arkham · 2002-01-10 08:32 · Score: 2

Not sure what language you're using, but HappyDoc is popular amongst python developers.

It does a really nice job generating (HTML, text, etc.) documentation from python code __doc__ strings and source code.

--
- Vincit qui patitur.

Re:PEBKAC by einhverfr · 2002-01-10 08:32 · Score: 2

OK. Aside from those rare people that have an ability to go down a row of Linux (or Windows 2k, or Mac OS X) machines and cause every single one to stop responding (yes, I have known a few such people), it is never the fault of the user. (OK. Here it is probably not the user's fault either, but in these rare cases, it may not be the developers' fault either).

I knew one person who could crash not only every computer she ever worked with but also managed to crash telephones with amazing regularity... I suspect the cause here is electromagnetic ;)

But aside from these rare instances, program crashes are the result of bad code somewhere, not the result of anything relating to the user. Code, ideally, should be designed to stand up to all user experience.

--

LedgerSMB: Open source Accounting/ERP

This monkey gets insightfull? by cybrthng · 2002-01-10 08:33 · Score: 2

"If an application crashes, it's the developer's fault. Period. End of story. It is NEVER the user's fault. "

Oh yes, That is really how the world works.

How about when LyX is such a painfull program to work with that i throw my PC out the window, can i blame that on YOU and the developers since it ISN'T my fault?

How about when i can't read a sign because there is glare and i crash run over a few school children, it isn't my fault but the construction firms fault because they dind't angle the sign right and i have the right to be ignorant because i'm a user.

bug off

Answers to stupid interview questions by PD · 2002-01-10 08:35 · Score: 2

The next time someone asks you that inane question "What is your greatest weakness?" you can just answer that writing documentation is your greatest weakness, but sometimes you've got to do things you don't like to do, so you tend to rely on document generating tools. Nobody likes to do docs, so he'll know exactly what you mean, and you can pat yourself on the back for answering a stupid question in a way that makes you look smart.

--
If tits were wings it'd be flying around.

Some things I used to use... by Uttles · 2002-01-10 08:40 · Score: 2

I like this program called Note Tab for windows. It's downloadable fom shareware.com in a free lite version. It's really quick and easy, but powerful for text editing.

Nothing beats BBEdit though, nothing. It's only for Macs, which is killing me since I haven't bought a Mac lately.

--

~ now you know

Re:PEBKAC by iamabot · 2002-01-10 08:41 · Score: 2, Funny

I blame society.

Another vote for LaTeX here by Anonymous+Brave+Guy · 2002-01-10 08:42 · Score: 5, Insightful

Put me down for LaTeX as well, please. In its favour (in this particular context)...

It takes input in a text format. Use CVS, your favourite editor, etc.
It also produces excellent quality output, and generating HTML, PostScript and PDF output are all straightforward with standard tools.
It can generate things like cross-references, tables of contents and citations very easily.
There are good packages available for free that can typeset code right out of the source file.
There are freely available and very powerful diagramming tools that plug right in. (Anyone know of a speciality UML drawing package, BTW? The usual tools are OK, but I've never found, say, some Metapost macros to make it completely trivial the way it could be. Surely someone must have written some!)
The maths typesetting is all there if you need it, of course. That's very useful if you're working on a scientific app and need to document the algorithms as part of the design, and it doesn't get in the way if you don't need it.
It's available for minimal money and effort.
It's highly extensible. If you need to do something that doesn't come as standard, you almost certainly can (and someone else almost certainly already has, and put it on CTAN for you).

The only downside I can think of is the learning curve. Basic LaTeX use is fine, but for really good output, you're going to want your own class file and/or packages. That's fantastic once you've got it -- all your docs follow a consistent style, and you can make it easy for newbies to learn the tool. Someone has to be pretty sharp to write the class/packages in the first place, though, or you have to be prepared to buy in expert help for a couple of days.

--
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.

Ten Reasons Why TeX/LaTeX is Better than Word by klund · 2002-01-10 08:44 · Score: 5, Insightful

LaTeX math mode is a thing of beauty. Equations come out looking correct. Mathematical expressions in Word are treated as an afterthought. Equation editor is evil.
TeX is guaranteed to be bug free. The author, Stanford Professor Donald Knuth, will send you a reward check is you find a bug. The reward is currently $327.68 (that is, 2^15 cents).
TeX is free (as in beer) and free (as in speech).
TeX has real comments. Anyone who doesn't comment their code is an ass.
TeX provides a full, turing-complete, language. The text produced by your input file can be the result of conditionals (which I use to reuse sections in different documents) or the result of complicated calculations. In the TeXbook, Knuth demonstrates the power of the TeX language by defining the \primes{n} command, which calculates and print the first n primes (see page 218).
There are no LaTeX "macro" viruses. You can safely receive LaTeX documents by email and not worry about it reading your OutLook address book and mailing copies of itself to all your friends.
LaTeX has no GUID (Globally Unique Identifier). Word documents are embedded with a code than can be traced back to your computer (the police captued the author of the Melissa virus by tracing his GUID). Big brother Bill is watching!
LaTeX versions are not incompatible. The file format has never changed. I have LaTeX files from 1989 that work without problem in the latest version of LaTeX.
There is no undo feature in TeX. This is a good thing. No one can ever seen earlier versions of your TeX document by pressing the Undo button.
LaTeX documents are small and lean. What's the smallest Word file on your computer?

--
My word processor was written by Stanford Professor Donald Knuth. Who wrote yours?

Re:Ten Reasons Why TeX/LaTeX is Better than Word by Yarn · 2002-01-10 10:34 · Score: 2

11. dvipdfm is your new god
12. proper ligatures!
13. doesn't loose bits of your document without huge amounts of encouragements

But, there are places where I don't like it. I think it needs a pre-processor or something. My problem:

\def\begeq{\begin{equation}}
\def\endeq{\end{equation}}

...

\beq
\frac{foo}{bar}
\eeq

...

! LaTeX Error: \begin{equation} on input line 54 ended by \end{document}.

Now, I'm (obviously) not an expert, but I've not found a way round this. I get fed up with typing full commands out.

Oh, and I tried making a document style once and now my brain is damaged.

--
-Yarn - Rio Karma: Excellent
Re:Ten Reasons Why TeX/LaTeX is Better than Word by matsukio · 2002-01-10 12:32 · Score: 2, Informative

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 \]).
Re:Ten Reasons Why TeX/LaTeX is Better than Word by CatherineCornelius · 2002-01-10 14:54 · Score: 3, Funny

There are no LaTeX "macro" viruses.
Unless you count the liveware virus that makes you want to escape every period\. I'd call that pretty macro\.
Re:Ten Reasons Why TeX/LaTeX is Better than Word by Yarn · 2002-01-11 03:01 · Score: 2

Heh, that was copied part way through me wondering if \beq had been defined already and changing it to \begeq

It still failed with \beq used throughout, and with \begeq.

--
-Yarn - Rio Karma: Excellent

Re:HTML by ChristTrekker · 2002-01-10 08:46 · Score: 5, Interesting

You missed one of the nicest features of using HTML/XML for documention: the fact that with CSS you can get basic content transformation.

What does it mean? It means that you can have rules for online display (that we're most familiar with), different style rules that kick in only when you print (implemented in Mozilla and Opera), and different rules only when you are projecting a presentation (implemented in Opera). This lets you make it accessible on the WWW, yet write your documentation only once without futzing with a nicer "print friendly" copy. If you do a presentation, you can point your audience to the very URL you're using for their later reference. Less chance for confusion.

--

Constitutionally Correct

Re:PEBKAC by mcelrath · 2002-01-10 08:46 · Score: 2, Insightful

Hardware issues?

It's a word processor, not a hardware driver. Unless ALL your apps are crashing, it's the software developer's fault.

Misconfigurations?

Again, the developers fault. The application should perform predictably and not crash for all possible combinations of configuration. You cannot possibly prescribe or predict what users will do with your application that you might not have anticipated.

If it was a linux program, would you say the same thing?

Absolutely.

--Bob

--
1^2=1; (-1)^2=1; 1^2=(-1)^2; 1=-1; 1=0.

Windows Crashing, taking Word with it. by ka9dgx · 2002-01-10 08:50 · Score: 2

We had a problem that too me a year to figure out, it turns out the HP 4000 Laserjet Driver needs WIN87EM.DLL to figure out page layout stuff, and when word uses the printer driver, it may, or may not be available. (Reference pointer counts get hosed, or something). This causes no end of grief, as the users would get a Fatal Exception 0E and blue screen of dead (BSOD) all the time. Once I came across the cure, everyone was quite happy.

The fix? Copy \windows\win87em.dll to an EXE file, and put a load= command in win.ini. Ths fixed ALL of our problems with Windows 95, 98, and Win98SE. We leave machines one all the time, and have a remarkably low (for windows) amount of trouble. Most workstations stay running until they are shut down. Our servers used to run for months on end, but now last the time between "Critical Updates" (AKA I can't write bounds checking software properly, so we'll fix it later) required reboots.

The point of all this? The drivers for printers, and scanners, and almost anything can hose a system. It's not likely to actually be the application's problem.

--Mike--

Re:PEBKAC by Carpathius · 2002-01-10 08:52 · Score: 2, Informative

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.

Re:PEBKAC by dillon_rinker · 2002-01-10 08:53 · Score: 2

If an application crashes, it's the developer's fault. Period.
True. And when a car is crushed, it is the auto maker's fault. A well designed car would be strong enough to be undented even when by two freight trains simultaneously.

Also, mechanical problems are the auto maker's fault even if the car owner replaces the every component of the drive-train with completely different ones from other cars and uses tractor tires and runs on kerosene instead of gasoline and uses dishwater in place of oil.

(Translation: developers CAN develop the perfect, uncrashable app, but there are many competing constraints; cost is not the least of these. And in a Windows world, developers should not be blamed if their application fails to function because the user has upgraded the OS three times and said "Yes" every time an application asks "The current version MSVCRT40.DLL is newer than the copy replacing it. Replace it anyway?")

FrameMaker?? by Belly+of+the+Beast · 2002-01-10 08:55 · Score: 2, Insightful

I used to use FrameMaker until Adobe started busting engineers for making speaches. I last built an 800 page spec with FrameMaker that included timing diagrams, drawings, etc.
Forget Word. Even with just the ASCII txt from the above document in outline above crashed it every time. FrameMaker was rock solid for the whole project with multiple authors, but I will never use allow it to be used here again after what they did to Sklyarov. Too bad, it did perform well.
Evolve or go extinct Adobe.

Re:PEBKAC by FortKnox · 2002-01-10 08:56 · Score: 2

If an application crashes, it's the developer's fault. Period. End of story. It is NEVER the user's fault.

I poured lead shavings all over my computer and monitor. Since you've proven it isn't my fault that the programs don't work right, I'm gonna go sue Dell!

Maybe you shoulda said "most crashes" instead of "all"??

--
Good quote, too many chars. Seriously, the slashdot 120 char limit sucks!

Adobe Framemaker by L-Train8 · 2002-01-10 08:57 · Score: 2

Framemaker can handle the large documents without the weird problems of Word (losing formatting, text disappearing, crashing, etc). It can format your docs nicely for pretty printouts. And Framemaker documents nicely convert to PDF, since Adobe makes both formats.

The downsides are that it's expensive (~$800), and it's made by the people who sicced the FBI on Dimitry Sklyarov.

--

Don't forget that Friday is Hawaiian shirt day.

Re:PEBKAC by Omnifarious · 2002-01-10 08:58 · Score: 5

A car crash isn't the same as an application crash, sorry.

Almost all application crashes are the developers fault. Only a very tiny percentage (< 0.001%) of application crashes are ever the users fault. Some of them may happen because the hardware or OS is buggy. But, that's not the user's fault. If the user goes into the registry and totally mucks it up, it still isn't the users fault. Even under Linux. If the user unplugs cards randomly from a non-hotswap PCI bus, that's the users fault. If the user breaks their system in some physical way, it's their fault. It is not ever acceptable behavior for a program to crash in the absence of a physical problem with the computer.

--
Need a Python, C++, Unix, Linux develop

Word is horrible by coyote-san · 2002-01-10 08:59 · Score: 5, Insightful

MS Word is about the worst tool around for writers.

The problem is that it forces, FORCES, you to deal with presentation issues at all times. When I'm writing, I want to focus on the content. How is the material broken down into major sections, into chapters, into topics? What information needs to be presented before a new topic will make sense? What topics will be treated as reference material, needing easy lookup?

This is hard enough to do with regular interruptions, but with text it's possible. I write an outline, DocBookify it, then write straight text within it while using minimal tags. When I'm happy with the content, I work on presentation (and usually loop between them a few times.)

But Word is so damn helpful that I'm constantly interrupted. I mispelled a wrod or two, gotta fix it NOW. Esp. with the increasingly intrusive "autocorrection" that insists on "fixing" things. (And don't get me started on it's ideas of what a properly formed URL looks like, never mind the RFCs.) There's the issues around the Redmondian English. My grammar isn't perfect, but highly technical material often requires extremely complex sentences to adequately convey the nuances. Green lines are another distraction. Then there's the whole issue of lists, tables, indentations, etc. sucking your attention because you're forced to deal with presentation before you're entirely sure what's going into them. (Two tables or three? What drives columns, what drives rows?)

Is it any wonder I, and many other people, find Word documents to be unusually vacuous? Not every text document in a Jon Postel RFC, of course, but there seems to be a direct correlation between the meat in a document and its original format. Straight text seem to be written to HS or college level, Word documents seem to be written to Jr High level at most. The problem is the polish - Word documents often strike me as first or second drafts, not finished documents. But they sure are pretty.

--
For every complex problem there is an answer that is clear, simple, and wrong. -- H L Mencken

Re:Word is horrible by ChristTrekker · 2002-01-10 09:25 · Score: 2, Interesting

I completely agree. I want to write in HTML (or some equivalent) and deal with content primarily. Style issues can be left to somebody else that has a clue how things are supposed to "look nice". (I sometimes find myself linking to the W3C Ultramarine CSS, because though I know CSS rules I don't have a sense for style.) If there were a good HTML text (not WYSIWY-won't-G) editor that felt polished (not hackish) I'd love it. Much as I like BBEdit, it's not there yet.

--
Constitutionally Correct
Re:Word is horrible by RadioheadKid · 2002-01-10 10:44 · Score: 3, Informative

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
Re:Word is horrible by dublin · 2002-01-10 12:45 · Score: 2

I have a love-hate relationship with Word, and in many ways, I really don't like it much, but it's clear from your comments that you haven't invested the time to learn how to drive it very well.

Word does not force you to deal with formatting issues as you compose - it's not as transparent as troff here, of course, but it can be made to present the text without much of the formatting, and can be told not to attempt things that obviously annoy you, like grammar checking and spelling autocorrection. (I agree the grammar engine is junk and doesn't understand proper sentence structure or the proper use of commas in any non-trivial sentence.)

Word is a pain, but I've also created staggeringly complex documents in it - in fact, last year I helped a good friend prepare his dissertation, which was already partly in Word, but needed a lot of formatting work.
Dissertation? More like a phone book, really - it's 650 pages of extremely complex text and diagrams involving some extremely complex annotated text diagrams and bizzarre fonts for ancient Hebrew (over 75 pages of this alone, annotated and color-coded to reveal complex patterns) as well as a number of strange pheonetic marks. (My friend is a brilliant and innovative linguist.)

In addition, I recently tried to build some new marcom (ad) materials in PageMaker, but gave up in disgust after spending nearly two days wrestling with the tool. Other than the lack of a full color palette for text in Word 97 (which may be fixed in later releases), I was able to build what I wanted (which was fairly complex) in three hours in Word. The really cool thing is that this document will be usable in StarOffice when they fix the textbox bug - other than that, it imports just fine.

Word is really a farily decent product, probably the best thing in the MS portfolio, other than Visio, which they bought...

--
"The future's good and the present is nothing to sneeze at." - Roblimo's last ./ post
Re:Word is horrible by dublin · 2002-01-10 13:41 · Score: 2

Oops, posted too soon. I was going to add that although you can do complex documets in Word, doing so for documents of over a couple of dozen pages is risky, and sooner or later, espcially as your document gets longer, Word will corrupt the file, so you are forced to keep each chapter in a separate file. For this reason alone, Word is not the best choice for documentation.

Also, there are those maddening times when the demons of Redmond take over and you just *can't* make it format things the way it should, or worse, you wind up with a document like one I have, which corrupted the Table of Contents along the way - any attempt to get word to refresh the TOC wil botch it completely, so I now have a TOC in which I have to place the page numbers manually. This takes time, but not as much as re-creating the document template or trying to fix the problem, which I've already wasted hours on.

Word is reasonably capable in some respects, but way too flaky in others.

--
"The future's good and the present is nothing to sneeze at." - Roblimo's last ./ post

The Best Solution by FFFish · 2002-01-10 08:59 · Score: 3, Interesting

There are currently only two good long-document solutions:

FrameMaker, from Adobe.

Ventura, from Corel.

They both have roughly equivalent functionality. FrameMaker is more accepted in the technical writing world. Ventura has a much, *much* better user interface. Ventura also has an incredible user support group. The latter two aspects put Ventura in the lead by several lengths, in my opinion. A feature comparison is available here. (Its automatic database publishing engine is worth it's weight in gold!)

Ventura is currently in beta-testing for a next-edition release. This edition is going to include XML support, presumably integrated with SoftQuad's products. Given that WordPerfect has had good SGML support for years, I find this to be very, very exciting news.

If you can get over any misgivings over the Corel name, you'll find that Ventura is the ultimate in long-document publishing. It's been around since 1986, and is more feature-complete than Quark, PageMaker, InDesign, and FrameMaker. And of those, FrameMaker is the only application that can be considered to be in the same class. Quark, PageMaker, and InDesign are short-document (ie. magazine advertisement layout) programs, and are absolutely horrible for use in long-document publishing.

FrameMaker and Ventura both fully satisfy your needs. Both can take in XML/SGML. Both produce PDF. Both can create HTML. Both handle documents thousands of pages in length with thousands of images. Both kick the living shit out of MSWord!

You only need to decide which is going to be easier to use, how much you'll want community support, which set of functionality you need, and how much you want to spend.

My money is on Ventura.

(It is, in fact, the only application I've ever used that I look forward to using. Every time I start it, I'm delighted!)

(Ventura users tend to be very enthusiastic about the product. We also tend to wonder why anyone would ever use anything else: we've tried the rest, and figure this is the best. :-) )

--

--
Don't like it? Respond with words, not karma.

Re:The Best Solution by FFFish · 2002-01-10 11:56 · Score: 2

Bullshit. Complete and utter bollox.
For starters, the comparison table does show XPress, and shows that it's a piece of shit.
It doesn't do tables. It has endless colour control problems. It fucks up PDFs. It doesn't do ToCs, doesn't do indexes, doesn't do equations, doesn't let you anchor graphics to text. Doesn't do bullets, doesn't do relative indents. Freaking list of what it can't do goes on and on and on.
It would take $10,000 (that's ten thousand dollars! [see below]) in third-party extensions to gain functionality comparable to that of Ventura or FrameMaker.
Finally, it has one of the worst user interface that's ever been foisted on users.
Quark is a good enough application if all you're doing is laying out a magazine advertisement. But for god's sake, no sane and informed individual who is attempting to do long-document publishing would ever use it.
Quark is definitively NOT a long-document publishing application. It simply does not have the functionality that such a task requires. Period.
Footnote: extensions required to make Quark as functional as FM or Ventura 8.
Quark PC-version Xtensions Quark PC-version Xtensions AdTracker $ 80 AutoLink $ 60 AutoSave $ 40 Azalea C39 Tools $150 Azalea I2of5 Tools $100 Azalea PostTools $ 60 Azalea UPC Tools $150 Bookletizer $ 70 BoxStyles $ 50 BureauManager $130 Class $ 90 Colbut'ns $ 80 ColorManager $150 CopySet $130 CropsXT $ 50 Dashes (Hyphenation) $300 Digital Pilot $100 DiHyph XT (Custom Hyph.) $200 DocLock $ 50 EDGAR Filter $400 File Manager $150 FlexScale $ 60 FlightCheck (tester) $400 FontIncluder $100 FourColors and One Image $ 20 fXT (footnotes) $300 GridMaster $ 50 HexWeb $350 IndeXTension $100 INposition Lite $400 Ishadow $100 JobSlug $ 60 KeepTool $ 50 KeyFinder (cheatSheet) $ 30 LinkWalker $ 40 Managing Editor XT Pro $120 MasterMenus $ 70 MultiSpec (cut'n'paste) $100 Navigator XT $ 70 NotePad (Electronic Post-its) $100 PageCopy $ 90 PageShot $ 90 Photoshop Import $100 PianzHang (large Doc Mgmt) $900 Picture Manager $200 PM-Q XT (PMkr 5-6.5 -> QXP) $100 PowerBalance $ 70 PowerRules $ 70 Printer's Spreads $180 PrintGrabber XT $ 70 PrintShop Mail (mail merge) $400 Quark Design $ 35 QuarkImmedia (multiMedia) $995 QuarkXpress $995 QuarkXpressPassport $1495 Multi-language doc creation QXPress Visual Quickstart $ 30 Resize XT $100 Sydney XT (filing system) $300 Sonar Bookends (index) $200 Sonar TOC $100 Spellbound (spellChecker) $200 Story Editor $165 TakeNote (stickyNotes) $ 60 TB Grids $150 TeXTractor (export filters) $150 Tiff Export $100 TimeStamp $ 50 Vision Contents (TOC) $150 vjXT (vertical justification) $150 Web-Ready Art $165 Windows Design Collection $100 Windows Text collection $100 Xnudge $ 30 Xspec $100 Xdata $300 Xtags $200 York's XTable $300 York's Xmath $400 Zoom Tool $ 40 ____________________________________ All PC Xtensions plus QuarkXPress $12,845 or QuarkXPress Passport $13,345

--

--
Don't like it? Respond with words, not karma.

For a real-world example... by devphil · 2002-01-10 09:00 · Score: 5, Informative

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)

roff by PotatoMan · 2002-01-10 09:01 · Score: 2, Insightful

For most documentation, I like either texinfo or *roff. Both will convert to either HTML or Postscript. Texinfo gives you Info docs as well, and does a better HTML conversion.

For simpler documents, roff works just fine. And it follows the Unix philosophy, so you get pic, tbl, and eqn for special-purpose formatting.

Our internal docs needed to use Framemaker (in order to be compatible with a vendor tool), and we had a program to take a simple mark-up and turn it into MIF. I replaced this with a groff to HTML and Postscript system. The HTML pages had a 'print' link that would load the Postscript and give the user a nice looking document.

Most of this stuff is a matter of taste.

Pod - Perl's Plain Old Documentation by Big+Stick · 2002-01-10 09:04 · Score: 2, Informative

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 by Anonymous Coward · 2002-01-10 09:05 · Score: 2, Informative

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 wouldn't do that... by Da+VinMan · 2002-01-10 09:06 · Score: 2

Heck, you can use 'aft' mentioned above, and get that much, and much more.

You could just as well recommend he use HTML itself; it would save a bunch of time.

However, neither of those solutions meets the stated quality requirements.

--
Please mod this post only if you think others should/n't read this. I have enough ego^H^H^Hkarma. Thanks!

FrameMaker + mif2go = almost any output you like. by Rikardon · 2002-01-10 09:12 · Score: 2, Interesting

Try FrameMaker 6.0 and mif2go if you want to produce HTML and PDF from the same set of master source files. I've used them with spectacular results, for docs ranging from 20 to 350 pages, including Table of Contents and Index. mif2go does help files, too -- WinHelp, MS HTMLHelp, JavaHelp, etc.

We have a user manual (350+ pages) and a demo document (~60 pages) that contains a subset of the stuff in the manual. We used to keep one copy of each document in PageMaker (hey, before I came along it was WordPerfect; give me a break!). This required constant, simultaneous editing of the almost-identical sections in both documents. It introduced errors and inconsistencies, and it effectively doubled my editing workload, since the sections we edited most often were the ones in the demo document. Worse, PM isn't suited to long-document problems like re-numbering sections. Any time we added a new section, I had to renumber, by hand, all sections that came after it, including cross-references to other sections (there are hundreds of these). I knew there had to be a better way.

Three years ago, I switched us over to FrameMaker. Now, I keep ONE set of master documents, from which I produce print, PDF, HTML and Help files for both the manual and the demo document.

Here's how it works:

Instead of one big file, I have 31 separate FrameMaker files, each of which corresponds to a section or chapter in the user manual. I have two "book files": one for the manual, which includes all 31 section files, and one for the demo document, which includes only three.

One of FrameMaker's most powerful features is its "conditional text," which lets you tag certain text for display only on certain conditions. In my case, I created three tags: ManualOnly, DemoOnly and Normal. Most text in all sections is Normal. But, some is ManualOnly and some is DemoOnly; for example, there's a completely different introductory subsection in the demo version of Section 1. That part is tagged DemoOnly; the intro subsection for the user manual is tagged ManualOnly, and the rest of Section 1 is tagged Normal. Now, deciding what gets tagged how takes a bit of work, but once it's done it simplifies things greatly: I open the book file I want, set the display to "Normal" along with "ManualOnly" or "DemoOnly," depending on which book I want, and print. Or, I can save as PDF -- a feature built right into FrameMaker. Note that the sections are numbered differently in the demo document than they are in the manual. That's OK; Frame handles the renumbering automatically, and even renumbers any cross-references between sections as needed! It likewise generates the Table of Contents and Index for me, with page and section numbers as appropriate.

Now, that works fine for print and PDF. What about Help files?

This is where mif2go comes in. mif2go generates FrameMaker Interchange Files (MIFs) from your FrameMaker originals and converts them to WinHelp, JavaHelp, HTML, HTML Help, XHTML: you name it. mif2go is US$299, produced by a small outfit called Omni Systems. The price includes free tech support (email only) for a year, and they have been VERY responsive to email, usually responding within the day. The only comparable conversion product I know of for FrameMaker is WebWorks Publisher, which is produced by a self-important corp that charges three times as much for its software that, IMHO, works far less well than mif2go (and yes, I've tried both; a demo version of WebWorks even comes with FrameMaker 6.0).

Before mif2go, help file creation went like this:

export FrameMaker section files to RTF (with FrameMaker's lousy RTF filter), losing most of the markup in the process, such as cross-references.
use a HAT (Help Authoring Tool) like RoboHelp to re-format what didn't translate properly, and to replace all the missing links. This usually took about six weeks, and introduced inconsistencies (like spelling mistakes) from the original files. It also had an ugly format, and some tables in our original document just WOULDN'T work no matter what we tried.

Here's how it works now:

Choose File > Save Using Mif2Go.
Double-click the .hpj file that mif2go generates, to compile the help using the (free as in beer) Microsoft Help Compiler.

Done. Perfectly-formatted help files, in less than five minutes. HTML output is much the same.

I have yet to see anything with the combined power of these two. FrameMaker is available for Windows, Mac and a couple of flavours of Unix (though unfortunately not for Linux), which is a heck of a lot better than you can say for LaTeX, which I wouldn't touch with a barge pole. For serious document work, give me WYSIWYG anytime: I can manage the layout -- even simple things like widows and orphans -- much more easily in a GUI than I can from a basic text editor.

And finally, FrameMaker is rock-solid. I use it every day, for serious work, and it has crashed maybe four times in the three years I've used it. I can't think of any other piece of Windows software that has been so reliable.

A word of warning: I've made this sound like a Great Thing, and it is. But it's not easy to begin with. FrameMaker has a pretty steep learning curve; it's been said that you can do anything to a text document with Frame, but nothing easily. However, your coding background will probably give you a great headstart. Some of the things, like the automatic renumbering of sections and cross-references I mentioned, will be much easier to set up, for example.

Good luck -- and stay away from Word.

Docbook clarification by VValdo · 2002-01-10 09:13 · Score: 2

I see some posts from people talking about DocBook as if it's an application-- it's not. Docbook is a DTD (Document Type Declaration): it's a specification of tags used to markup documentation, much like HTML's DTD (http://www.w3.org/TR/REC-html40/sgml/dtd.html) describe those tags used to mark up a web page.

So, like, documentation written using the DocBook DTD will look something like a web page, only the tags that surround the content are specific stuff you'd find in documentations. Some of the tags look like this:

<book>
<chapter>
<title>
<para>
<note>
<procedure>
<step>
<userinput>
<figure>
etc.

All you really need in order to write documentation in DocBook is an editor that can handle SGML or XML and can use DTDs. Files marked up using DocBook are simple SGML (or XML) text files, and you can alter how they are displayed or printed with .CSS just like a web page.

So you can have a single source for all your documentation, such as a manual for your software, and output from docbook to any other format-- PDF, HTML, XML, or print.

There are lots of open source programs out there for writing XML files that let you import a DTD, some of which are specifically geared towards Docbook. Other applications take files marked up using DocBook and, along with a .css file to say how to display each of the tags, convert/format them into whatever you want: .eps, .pdf, .html, etc.

W

--
-------------------
This is my SIG. There are many like it, but this one is mine.

Re:PEBKAC by Remote · 2002-01-10 09:13 · Score: 2, Insightful

Yeah. Considering the prefect program is yet to be written, then there will always be some poor code somewhere.

Ive been using MS-Word for years too, many versions, on anything since MS-DOS4 to W2K. There are things I dont like in Word, but stable it is.

For example, my home machine runs Windows like a charm, but if I run Linux/XFree86/KDE/Mozilla and load a page with a few large jpgs (which IE would just eat) it begins to swap and stop responding to *any* imput except for the power CHORD! Once I just let it spin to see how long it would take. AFter 2h40min I gave up. I am sooo obviously doing something wrong, I just cant figure out what it is. So dont tell way0utwest to shut up, hes tryin gto help and giving sound advice.

DocBook is my choice by slagdogg · 2002-01-10 09:14 · 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!

--
(Score:-1, Wrong)

I think it is... by Da+VinMan · 2002-01-10 09:16 · Score: 2

...because the version management software would need to be 'aware' of all the possible formats you could save in it. It would need to know about MS Word, HTML, Rich Text, WordPerfect, Works, AbiWord, TeX, Postscript, Write, etc. etc. etc.

The point is that there are probably over 200 word processors out there. Some of them are proprietary format too. Oh, and they can all change their save format from version to version of the software.

And that's just word processors. Now, think about spreadsheet software, presentation software, etc. etc. etc.

It really is a lot to ask of the version management software.

It's not impossible. I'll never say that. But is it really reasonable?

--
Please mod this post only if you think others should/n't read this. I have enough ego^H^H^Hkarma. Thanks!

Ever hear of NegWeb or NoWeb? by Nindalf · 2002-01-10 09:22 · Score: 2

NegWeb is a "semi-literate" programming tool. Basically, it lets you define chunks of output files in any order, in any location in input files. So if you want to put the chunk of documentation for a feature in LaTeX or HTML just before the chunk containing its implementation, you are free to do so.

It differs from other literate programming tools in that it doesn't have any concept of formatting the NegWeb source as a whole. Literate programming started with Donald Knuth's WEB, which arranges Pascal in the same way that NegWeb arbitrary text files (an operation called "tangling," since the results are compilable, but not pretty), but also indexes and pretty prints the Pascal and treats the text between the code chunks as TeX (called "weaving"). Knuth later created CWEB, which does the same thing, but for C instead of Pascal.

My problem with this approach is that when you go to edit it, you deal with the ugly TeX source, or you reweave constantly. Also, unless you are such a TeX wizard that you do it without ever thinking or looking things up, you are distracted from working on your functional output by fiddling with the formatting. The NoWeb approach is to have the plain text source the most readable version of the source, on the principle that code is most often read to be edited.

The name is a play on NoWeb, which is essentially a simplified and generalized CWEB, since NegWeb is essentially a simplified (some literate programmers would say "crippled") and generalized NoWeb. NoWeb is very extensible, and supports indexing and pretty-printing for a lot of languages, as well as using several different formatting languages for weaving, such as LaTeX and HTML.

Either would work for rearranging arbitrary ASCII text chunks into files: NegWeb is simpler, NoWeb is prettier.

You might be surprised at the freedom it gives you to factor your code into short, manageable chunks. It definitely helps to set up a few macros in your text editor to treat the chunk names as hyperlinks to find the definition of the chunk, and all places it is used.

LaTeX vs WYSIWYG by bcrowell · 2002-01-10 09:27 · Score: 3, Informative

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:

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.
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.
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:

No unicode support.
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.
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.
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.

--
Find free books.

XML, XSLT and Docbook - a near-perfect solution by swillden · 2002-01-10 09:28 · Score: 5, Interesting

I've been using XML and Docbook for a while now, and I really, really like it, particularly if you use Docbook as an intermediate format rather than what you actually write your documentation in.

For example, I've got some really nice stuff for building use cases in XML. I created my own DTD for a use case language (which I call UCML) that allows me to define actors, use cases, goals, glossary terms, etc. Use cases consist primarily of a sequence of steps (nestable) with links to actors, terms, other use cases or steps, goals, etc. along with some other tags that define the name, extends relationships with other use cases, termination states and conditions, preconditions, business rules, etc.

I also have some XSLT stylesheets that do a number of nifty things with these UCML documents. One stylesheet transforms UCML to HTML, complete with every imaginable hyperlink, tables of contents etc., and even deduces a bunch of relationships which it documents (and hyperlinks). For example, if a use case mentions an actor or another use case in its steps, the stylesheet adds a section to the HTML description of that use case that documents the fact that this use case uses (in the OO sense) that one, or that this actor participates, and adds similar information to the descriptions of the use case and actor that are referenced. This is just a sample, the stylesheet does a lot more, and produces very *usable* and consistent documentation.

Another stylesheet acts as a sort of garbage collector. Phases (groups of Use Cases intented to implemented together) and Use Cases can be marked as "dead", in which case the UCML->HTML stylesheet will "hide" them (they won't show up in the output). The garbage collector stylesheet takes this a step further and analyzes all actors, glossary terms, entities, goals, etc. and produces a new UCML document that does not include elements unreferenced by a "live" use case. So, I can mark some currently uninteresting use cases as dead, run the garbage collector, run the UCML->HTML stylesheet on the result and get a nicely formatted document that contains only the supporting information required for the included use cases.

HTML is not ideal for printing, though, and this is where Docbook comes in. I have a UCML->Docbook stylesheet that does essentially the same things as the UCML->HTML stylesheet. Then I can convert the Docbook to PDF, Postscript, TeX, etc.

I've also created my own XML languages for component models, architectural decisions documents and others -- it's pretty easy to gin one up whenever I come across another sort of highly structure document I need to write. Plus I have one that I use for simple, less-structured documentation that just provides sections, paragraphs, etc. Mostly I just have whatever->HTML stylesheets for most of these, since they're all intended to be read by developers who are less insistent than end-users on having printable formats.

So, I have nice, text documents that I can use EMACS on, manage in CVS, etc., stylesheets I can fiddle with (when I get sick of writing documentation I can always spend a little time improving the stylesheet code and justify it as "documentation" effort :-) ) and everyone else gets really nice docs from me. The biggest downside is that other people (non-programmer types who are uncomfortable with tagged text) are often uncomfortable with trying to edit my documents (sometimes it's a good thing, as it allows me to retain the "power of the pen", sometimes its bad as even trivial updates must pass through me).

The next steps with UCML are (1) figure out how to establish and maintain XMI-documented use cases and UCML-documented use cases and (2) write a WYSIWYG-like tool for editing them, for the tag-averse.

BTW, if anyone is interested in using the stuff I've described, drop me a line. I've been thinking about putting it up on SourceForge, but don't know if there's enough interest to make it worthwhile.

--
Note to ACs: I usually delete AC replies without reading them. If you want to talk to me, log in.

Re:XML, XSLT and Docbook - a near-perfect solution by swillden · 2002-01-10 10:51 · Score: 2

docbook2pdf. It's part of Jade and seems to do a reasonably good job. I need to learn more about how to customize the output, though, because there are some things that are not ideal.
I've only used the Linux versions of the tools, but I understand from the Docbook mailing list that I'm in the minority. Most users are on windows and it seems to work well on a wide variety of platforms. It should, there's no GUI to cause problems -- oh, wait, is that what you meant by primitive? I like building my documents with Makefiles myself, but others may feel differently.

--
Note to ACs: I usually delete AC replies without reading them. If you want to talk to me, log in.

Ventura still scares me. by Rikardon · 2002-01-10 09:30 · Score: 2, Informative

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:Ventura still scares me. by FFFish · 2002-01-10 11:09 · Score: 2, Informative

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. :-)

--

--
Don't like it? Respond with words, not karma.

Re:PEBKAC by mark_lybarger · 2002-01-10 09:31 · Score: 3, Insightful

yes, if your application needs (or can) work with a specific hardware which requires a specific configuration, then your application should take responsibility to ensure that environment is present. aborts are bad! they should not be tolerated. an application should not allow a dumb user or dumb hardware to crash it.

Re:PEBKAC by spectecjr · 2002-01-10 09:34 · Score: 2

I also assume that when he says "crashes repeatedly," he's talking about the application itself, and not the OS in general--hence cracked codecs, odd drivers, and the like shouldn't be messing with Word at all. (I realize that I'm speaking from a dream world where all applications have their own, protected memory, but that's not the user's fault).

So you expect an Application to work fine when, say, a specific graphics driver blows its stack when you use a brush created in a certain address-range in memory?

Sure, you can handle errors, but if you can crash the *DRIVER*, and the user-mode portion of *that* is what crashes the app, then what are you going to do?

--
Coming soon - pyrogyra

StarOffice 6 XML. *waves goodbye to Tex forever* by Nailer · 2002-01-10 09:41 · Score: 3, Informative

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.

A little off-topic but of note by Hangtime · 2002-01-10 09:51 · Score: 2

Since it seems we have two conversations going I thought I would interject with a form of documentation. In Code Complete Steven McConnell talks about the PDL or Programming Description Language. Basically its starts out as documentation but you keep refining each piece till you get to the point the easiest way to describe a function is through code. I now use PDL when Im coding prefacing everything with 'PDL- its an easy way to lift all the description out of the code later and gives anybody behind a good grounding in what my code is doing. Quite frankly I hate trying to make my way through someone else's code, its not fun. Had to once look through an Access-based program using Macros and modules developed by a brokerage. A book-think worth of code MAYBE a page worth of comments, DROVE ME INSANE! Oh well, PDL good stuff look into it, you will remember what you wrote and everyone around you will thank you for helping them understand.

Re:PEBKAC by 3am · 2002-01-10 09:53 · Score: 2

look at the other comments. a lot of people have used word, and it's worked well for most of them. myself included.

why does anyone here saying that a microsoft product is not necessarily bad get immediately attacked and discredited?

word is a good product. better than star office, from my experience in both (admitted a while ago for star office).

--

A: None. The Universe spins the bulb, and the Zen master merely stays out of the way.

Hardware stability? by MrResistor · 2002-01-10 09:54 · Score: 2

It seems like you have a lot of stability problems. Perhaps you should look at your hardware as the culprit? I've had more than a few experiences where I thought crappy code was causing all my crashes only to discover that my CPU was running hot due to a flakey fan or poorly installed HSF, or my hard drive was dying. Maybe your hardware just isn't up to the task?

I've used Word for a few years now and I've never had stability problems (although I nearly choked when you mentioned MS Word and HTML in the same sentence). Nor have I had any problems with OpenOffice 6.x, which I've been using for over a month now. OpenOffice is my recomendation for you, especially if you have legacy Word documents. I haven't run into problems with any of the MS Office formats in OpenOffice yet. It does like to warn me whenever I save to one, but so far it's been all bark and no bite. And, of course, it's available on multiple platforms.

--
Under capitalism man exploits man. Under communism it's the other way around.

I switched by fireboy1919 · 2002-01-10 09:56 · Score: 5, Insightful

I wrote a publication (16 pages, IEEE format) for Word and it was a REAL pain. Word stored the whole document in memory, which actually meant that part of it was cached to hard drive. I work in the Field of Computer Vision, so I necessarily had about 10 megs of images in there. Occasionally, that would be too much for the operating system, and I'd have to wait 15 minutes or so for the memory manager to catch and resolve some thrashing issues.

Also, every time I changed anything at all, Word would move around the pictures and mess everything up - even though I had all the pictures positioned as "absolute." At the end of the publication, any 3 minute change at the beginning of the document took half an hour to fix.
For the next publication, I did everything in Latex. The added bonus there was that format is separate from content, and the format descriptors where already written by IEEE (and by my school for my thesis).

--
Mod me down and I will become more powerful than you can possibly imagine!

Autoduck - Unsupported Microsoft by Embedded+Geek · 2002-01-10 09:58 · Score: 2

I hate plugging Microsoft, and I doubt this is the only tool of this ilk out there, but there's an unsupported tool they created called autoduck (page bottom) that we've used with some success. You put the documentation into your source code, marking them with tags. Autoduck pulls them out, then parses them into a help file or an RTF file for importing into Word or WP. Seems ideal for documenting APIs, but we've found other uses, too. I think it originally shipped with VB, but I'm not sure.

And, yes, I know that a flame could argue that many other commercially sold Microsoft products could be called "unsupported tools," so let's try to steer any jokes onto a different track...

--

"Prepare for the worst - hope for the best."

In praise of DocBook by PhilRod · 2002-01-10 10:08 · Score: 5, Interesting

Nobody seems to have mentioned the great advantages of DocBook here. Having written some bits of documentation for KDE, I've seen some of DocBook's advantages:

First off, it's fully compliant SGML or XML, whichever flavour you prefer. DocBook documents are stored as nice plain ASCII which can be processed with any SGML/XML tool you happen to have lying around.
Output options are virtually unlimited. IIRC, HTML, man, texinfo, plain text, (La)TeX and anything else you care to mention are available as output formats, with XSL providing a way to produce your own custom output.
The Crunch: Text is marked-up for what it is, not what it's meant to look like, so you needn't know a single thing about formatting while writing content and vice versa. You know the advantages of using CSS instead of hard-coding HTML. Well, they count for DocBook too.
Nifty features like creating tables of contents from the source and all that sort of thing that you thought only TeX could do.
I suppose I should mention that it's extensible, hence the XML version.

--PhilRod

--
KDE Documentation Team: http://i18n.kde.org/doc

TeX gone? Nope. by Grendel+Drago · 2002-01-10 10:10 · Score: 4, Interesting

Uh, no.

METAFONT is pretty much integrated into TeX if you're using... well, I've only used teTeX and MiKTeX, but there are scripts to autogenerate any fonts that are needed.

And... well, you can't compete with the userbase. It's been a standard for nearly twenty years. The original program is probably as close to bug-free as any large piece of software can possibly be. Did I mention the enormous userbase?

TeX is far from dead. It's Knuth's dream that a TeX file written today will be compilable and readable in a hundred years. Given how entrenched the system is, I think this is quite likely.

-grendel drago

--
Laws do not persuade just because they threaten. --Seneca

Re:TeX gone? Nope. by Nailer · 2002-01-10 13:06 · Score: 2

> Uh, no.

Well, you disgree.

> METAFONT is pretty much integrated into TeX if
> you're using... well, I've only used teTeX and
> MiKTeX, but there are scripts to autogenerate
> any fonts that are needed.

I'd be much happier if it wasn't. I'm more than willing to give it a go if there are soem I've missed, but almost all the scripts I've tried have had issues with certain fonts. Since these aren't part of Tex, their reliability seems to be more a concern. But I might be wrong - if you can point me to a reliable ttf2mf script or sample code I'd be grateful, and change my mind on the topic.

And... well, you can't compete with the userbase.

I think StarOffice is more than capable of competiting with the userbase of not only Tex but Microsoft Office, which is infinitely larger. It provides all the advanatages of a structured presentation independent documentation system, a modern font system, XML/XSLT, and a killer GUI editor (or just hack at in in vi and sh if you'd prefer). Now 6 is more modular and reliable, it really has a chance of doing well.

It's been a standard for nearly twenty years.

And it has a dwinling userbase because people that use computers these days are impatient and non technical. StarOffice represents a good chance to have Joe User create real documents, and is a joy for the mroe technical of us to work with.

The original program is probably as close to bug-free as any large piece of software can possibly be. Did I mention the enormous userbase?

So is hello world. As good as tex is, I don't see it ever appealing to Joe Average. And for the rest of us, XML won the file format wars and we're glad it did.

Mike

Re:PEBKAC by heikkile · 2002-01-10 10:12 · Score: 2

but you can NEVER take into account what a user can/will do

I disagree, strongly. If a program accepts user input, it ought to be prepared for anything. Accepting anything else is a direct way to crashes, security probelms, abuses, and other horrible things. Of course a program does not need to perform well when put to a use it was not intended for, but the least it can do is to fail gracefully. Yes, this means that the programmers will have to pay attention to the remaining 80% of the code, and yes, that is expensive. Just imagine if car producers were blindly assuming that nobody would drive over the speed limits, and would always be able to control their vehicles. How much cheaper cars they could produce! No need for seat belts, air bags, stronger frames...

--

In Murphy We Turst

Re:PEBKAC by cprael · 2002-01-10 10:14 · Score: 2

Actually, yes. Especially if you use a specific configuration, then say "go configure it", but don't bother to cover your tweaks.

Example from a few years ago. I was working with Oracle Video Server group. Their docs for the client said "go install and config the client, then install our software." What they didn't realize is that the "as shipped" configuration of the underlying hardware required a _very_ specific configuration to get it to work - including downloading the update patch and installing that OVER the driver set supplied with the hardware. Took a 9-step installation and turned it into a 32-step process. The client-side developers hadn't bothered to tell anybody (nor did they really realize...) that they were using an uprev version of the driver software, not what was shipped.

Always assume code is final... by Anonymous+Brave+Guy · 2002-01-10 10:16 · Score: 2

The sad thing is, in real life pointy haired people jump in after the prototype has settled and cut the rest of the development because "it's already good enough".

This is true, and the way the world works. Since you can't change it, it therefore makes sense to adapt your development process to it. Don't write "temporary" code. By all means prototype, but always write to production standard. No lazy organisation, crappy identifiers or forgotten error checking should be allowed, as a matter of good practice.

If you're going to leave an area of code unfinished for more than a few minutes, it's also smart to include some sort of marker message that comes up every compile/run to warn about this. That way, no code that's not up to standard ever goes unreported.

--
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.

SDF? by mOdQuArK! · 2002-01-10 10:22 · Score: 2

Is anyone using SDF (Simple Document Format)? I ran across it at http://www.mincom.com/mtr/sdf - the last update was at 25-May-99, so I don't think it's being actively maintained anymore (unless it's being maintained elsewhere).

Two problems with binaries in repositories by Anonymous+Brave+Guy · 2002-01-10 10:24 · Score: 2

There are two major problems with storing binary formats in repositories: diff'ing and merging. If you want to establish the differences between two versions, you are reliant on the tool that created the document to do this for you. (MS Word does, of course, but this is a problem in general.) Further, if you want to allow multiple people to edit at the same time, you can do it and merge semi-intelligently with text-based formats. I don't know of any word processor with a binary format where I can be editing chapter 1 of our main design document, my colleague can simultaneously edit chapter 3, and we can get all the changes back in with no more than a check to resolve any conflicts.

--
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.

Apache Cocoon... by graveyhead · 2002-01-10 10:28 · Score: 3, Informative

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;

The reason you hate writing documentation... by kindbud · 2002-01-10 10:33 · Score: 2

You hate it because you are doing it at the wrong time. Write your documentation before you write one line of code. Then proceed to write your code to implement the documented features, instead of later trying to document poorly documented source code. ;)

Viola. Cello. Whatever.

--
Edith Keeler Must Die

Re:No question - use LaTeX by CaptainCarrot · 2002-01-10 10:35 · Score: 2

And for the text editor itself, may I recommend NEdit? It's got a bunch of nifty customizable syntax-highlighting features, and LaTeX is among the built-in syntaxes. I use it for programming too, on VMS no less, where it works just fine.

--
And the brethren went away edified.

I don't understand the question by rho · 2002-01-10 10:37 · Score: 2

Are you writing design documentation? Or product documentation? i.e., are you writing for programmers or users?

Programmers almost never should write documentation for users, if that's what you're talking about. Docbook, YODL, AutoGen PodPeople MagicDoc... none are appropriate documentation methods for users.

Design documentation, however, is different.

--
Potato chips are a by-yourself food.

Re:StarOffice 6 XML. *waves goodbye to Tex forever by PONA-Boy · 2002-01-10 10:44 · Score: 2, Informative

*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.

-PONA-
King of the Who?.sig

--
+that's funny...I don't FEEL tardy.+

Use an Outliner by Lysander+Luddite · 2002-01-10 10:53 · Score: 3, Interesting

Use an outliner. There are several out there, the one that springs to my mind immediatley is Omni Outline (www.omnigroup.com).

Using an outliner allows great hierarchical structure allowing you to edit quickly.

A good outliner will also output to HTML/XML where you can apply a CSS file for both screen/print mediums. Mozilla, even IE 5+ will ensure your docs appear how you want. Heck, you can change the CSS file and not worry about the presentation at all. Just create a few CSS templates and off you go.

I don't know why you'd make it harder than you have to.

FrameMaker is a Very Good Solution. by snogwozzle · 2002-01-10 11:06 · Score: 2

I manage Technical Publications for small platform-agnostic music/audio SW technology company known for a browesr plug-in, but also established in the mobile world. My group does all the documents that the outside world (licensees, end users) see describing our products and how to use them:

End User Guides for GUI music editor apps
API References for our technology licensees (incl. Overview, How To Use, Method References, techNotes, etc.)
Quasi-marketing stuff like data sheets/specs/books

All these document types (and more, actually) can be delivered in plain HTML, HTML with a JavaScript viewer system, PDF, and we can even go to film for old-fashioned printing. (You, as in 'on paper, from a printing press'?) The output not only looks great, and conforms to the company's overall style/graphic identuty, it even looks consistent in all the output formats.

How do we do this? We build all our documents in FrameMaker, which does all the output except the HTML, which is done in the companion product WebWorks Publisher (WWP) from Quadralay. (Yes, I'm a Dmitry booster, and I do suffer from Adobe-user guilt in this regard, however my feelings are deeply mixed since as a denizen of the tech pubs ghetto I find FrameMaker is a solace to my otherwise tool-impoverished people...)

But it's not just the products you use -- your practices matter at least as much. Just as in good program design, good document design is matter of deciding on a set of elements and then using just the elements -- no jerry-rigging, no kludges -- to build the whole. With FrameMaker, the elements come from a template containing Paragraph and Character formats. In WWP you create a corresponding template with the HTML tags you want for the corresponding Para and Char formats, designed to reproduce (perhaps with the help of CSS style sheets) the look of the FrameMaker formats. Once you take into account all the included illustration and book part files, every document is a lot like a SW project with lots of hieracrchically dependent parts that all need to synchronize. Think of the output formats as 'build targets. ' Just like with coding, if you follow your own rules it all works out quite nicely.

Is this a lot of work to set up the first time? Yes indeed, but this is how the big kids do it.

Could a coder use FrameMaker to do documentation? Possibly, if it were the right person, though this would be more likely to work well if a tech pubs person were to set the templates up for the coder. However with FrameMaker at $800 a seat this approach is probably too spendy for most sizeable shops. This system works better with a smaller number of dedicated tech pubs people serving a larger number of coders.

Is there an easier way to automatically produce the same level of quality across a similar range of output formats? Not that you can achieve without tripling your tech pubs staff and tools budget.

Can you automatically turn a .h file into an API Reference? Depends how good you are with Perl. I have a tool of my own that turns a .h file into a formatted, cross-referenced, TOC'd FrameMaker file, but it doesn't pull source code comments into the FrameMaker document. Not because it couldn't -- it could, if that's what you want to do -- but because frankly in my experience most of that stuff needs to be so totally restructuired and rewritten anyway that it's almost always easier to just read the function signature and start writing. (With the source open in a separate editor window, of course.)

(Sometimes we rewrite source code comments too, but since we aren't publishing the source code in multiple formats, that just happens in BBEdit or CodeWarrior.)

Which brings me to a secondary comment on the article title "Developers: Writing Documentation" -- While I agree that all developers should certainly document their work, I wouldn't necessarily agree that what they write should automatically be used as the product documentation that the outside world is given. Because the talent of being able to communicate about technology is not the same talent as being able to create technology. It seems a comparatively small fraction of people get to have both talents. (And of those, a comparatively small fraction will admit they can do the one they enjoy less!)

Be a little wary of DocBook by beej · 2002-01-10 11:09 · Score: 4, Interesting

I've done Beej's Guide to Network Programming in DocBook (it used to be HTML). It works quite nicely for HTML output with NWalsh's stylesheets.

What was hard was getting it set up, and getting help out of the DocBook people in the know. (They can be pretty unapproachable sometimes.)

What was also hard was getting print output to work nicely. I was running fine for a while until I upgraded openjade, and then blammo--two-sided print output doesn't work anymore. Openjade simply refused to put the two-side directive in the TeX output, so I did it myself.

And what is it about my document that causes openjade to take 3 minutes to pump out TeX output, when it does the HTML in about 5 seconds?

Why is it that when I put two tables on the same page openjade/jadetex doesn't take that into account and keeps printing text off the bottom of the sheet?

The other place I've looked is Xerces/Xalan/Fop at Apache. I like the Formatted Objects idea, and it seems pretty sound. Also, the whole thing was about 827 times easier to set up than the jade stuff. Unfortunately, the code is alpha and doesn't work very well, sometimes crashing during the render.

"How does ORA do it, then?" I hear you asking. They have custom in-house tools for processing DocBook that have been in development for some time. Word on the street is that they might be releasing them soon.

Conclusion: if you want print output, you might have trouble getting what you want with DocBook at this time. At least when I code TeX it does what I say. (I don't recomment plain TeX for documentation. Maybe LaTeX since it's easier to convert to HTML. And pdf(la)tex produces nice PDFs.)

Re:PEBKAC by Mr.+Slippery · 2002-01-10 11:10 · Score: 2

...had inserted about 50 1024x768 jpg's and resized them down to about 1" square each. He couldn't figure out why one little presentation would barely run on his laptop...

So Powerpoint was too dumb to properly scale the JPEGs? Why am I not surprised...

(Of course, Powerpoint should have been taken out and shot long ago...I have yet to see a Powerpoint "presentation" with any meaningful content. It's PHB-ware, pure and simple.)

--
Tom Swiss | the infamous tms | my blog
You cannot wash away blood with blood

LaTeX by rnturn · 2002-01-10 11:11 · Score: 2

I'd go for LaTeX. Granted you have to get a little used to it. But I found that I could be more productive using emacs/latex/xdvi as an acceptable documentation generation toolset as I could be if I were lashed to a chair and forced to use some Windows word processor.

Years ago, back when I could recite pages from the VMS docset and could make my own grant bus cards, we used VAX DOCUMENT for documentation. As it I discovered one night, it was nothing more than an SGML (or SGML-like) front-end to TeX. We used it for project documentation sometimes cranking out manuals of several hundred pages. While I'm sure that some DOS/Windows WYSIWYG word processor might have done the job, it would (I'm positive) have been much, much more painful.

Sadly, the choice of tool that you use might depend on how long this documentation has to live. If you ever leave, will your employer know to look for a candidate that has experience in whatever tools you decide to use. It's unfortunate but your boss might force you to ``dumb it down''. Of course, we can all smile to ourselves over all those corporate documents that won't be readable in a few years when Microsoft decides to change the .doc format again. Happily, I have TeX/LaTeX files that are over ten years old that are still useful so you might point that out to your boss if s/he decides that you should go the MS route.

--
CUR ALLOC 20195.....5804M

No, you're an idiot by RebornData · 2002-01-10 11:24 · Score: 5, Insightful

I use Word almost every day, and while many of your comments are true for default behavior, you clearly have not attempted to actually learn the program. To take the issues in the order you cite them:

1. Word actually doesn't force you to deal with presentation issues at all times. Are you familiar with outline mode? I usually do my first drafts in outline mode, which allows you to focus entirely on content and structure independent of formatting. Outline mode works with styles to specify formatting globally for a given level in the outline. So if the top level in your outline applies to chapters, you can easily define a chapter heading style that will be automatically applied to all the top-level items. It really works well.

2. It's been said already, but it's worth repeating: Real-time spelling and grammar correction are really easy to turn off. Really easy.

3. Lists & indentations. You should learn how to use styles. This is exactly what they are for. For example, my default template has a "bullet list" style. If I want something to be a bullet list, I apply this style to it. The "tags" aren't visible, but they effectively are there. If I ever decide that a bullet list needs to be indented differently, or have square instead of round bullets, I can make the change once for the style. Once you've set up your default doc template with a reasonable set of styles, you never have to worry about presentation during early stages.

4. I don't understand what you say about tables.

5. "Word documents seem to be written to Jr. High level at most"? What the hell? This is broad generalization at it's worst. I bet more doctoral dissertations are written in Word than anything else. Although I did get a good laugh thinking about what the average grade level of a /. post would be...

Now, I'm not saying Word is the end-all be-all. I'm just saying that you're an idiot because of the 10000 things wrong with it, you've picked issues that are almost univerally untrue, and simply reflect that you haven't learned to use it.

Re:No, you're an idiot by wsloand · 2002-01-10 15:04 · Score: 2, Interesting

I bet more doctoral dissertations are written in Word than anything else.

I'm almost sure that that isn't true. Of the five people that I know who are writing dissertations at the moment, one is using Word, three are using LaTeX, and one is using something else (can't remember what, but it's neither of those two).

Word, by default, thinks about presentation first. I realize that your arguements state that all the defaults can be changed, but for the most part, people don't. It's very difficult to fix all the defaults, and when you go to another computer to try to fix things, you usually have to work to get things back to the way that you want them.

Also, Word is bloated. How many multi-hundred page documents have you seen written in word? In my and my friends and colleagues experiences, it starts choking around 20 pages and dies around 50. Start adding images/figures and it'll sputter to a halt about one less page per 50K of image or per figure.

I just finished writing a rather long document (about 40 pages), and the time that I spent on content was negligable. I adjusted the margins primarily. The system that I used is LaTeX. It worked out that I just use \filename{} to indicate a file name or directory. I used \button to indicate a button that I pressed. These were then defined at the beginning and I never think of them again. Also, it allows me to save the time of opening a massive editor (at least 20 seconds to load word on my computer while emacs loads in less than 5) each time I have to edit.

I use word for < 5 page or < 10 page documents, but it isn't designed well by default for large complex issues. It can do them, it just takes more work than other systems.

I would be interested to hear your rebuttal to these comments (unless you decide to flame).
Re:No, you're an idiot by RebornData · 2002-01-11 04:49 · Score: 2

Re: The dissertation issue:

How many English, Art History, or History PhD candidates do you think use LaTeX? I bet you're right about engineering PhDs...

Re: presentation first
Can't disagree there. That's definitely the out of box defaults, but one of the reasons it's bloated is that it's the kitchen sink and you can use it a bunch of different ways if you bother to learn.

Re: Long docs

I'm not a writer, but I have worked quite a bit with documents pushing 60-70 pages. There are definitely issues (though I haven't experienced quite what it sounds like you have).

I'm not sure I would recommend Word as the right tool for a multi-hundred page doc. I never said Word was the end-all be-all... there's a lot to complain about, and it just isn't suited for certain things. I've used a lot of different tools, from general business / consumer stuff like AppleWorks, WordPerfect and Word to more technical / specialized tools like FrameMaker, LaTeX and PageMaker. The right tool depends on personal preference and purpose. I once did my resume in troff because I wanted a single source to generate good-looking output both in ASCII and postscript.

There is certainly a lot to complain about with Word, my main beef is that this guy picked the wrong ones.
Re:No, you're an idiot by RebornData · 2002-01-11 04:52 · Score: 2

You've got some good points. Too bad the original poster didn't pick things like this to harp on... I was in no way making a general defense of Word, just pointing out that these particular issues aren't entirely valid. I sure wouldn't do my dissertation in it...
Re:No, you're an idiot by RebornData · 2002-01-11 05:27 · Score: 2

Well sonny, if you want to start an experience-based pissing contest, I'm happy to. I've had experience with Windows going back to 2.x. I used Word prior to it's Windows-based releases. In terms of doc tools, I've make substantive use of nroff / troff, LaTeX, FrameMaker, PageMaker, WordPerfect, AppleWorks, WriteNow for the NeXT, ed, vi, emacs, DOS edit, and I'm sure I'm forgetting some. I'm not sure how that's relevant to the conversation, but so there! :-P

I think you're a bit disingenuous claiming that outline mode and styles are "obscure". Sure, you're not *forced* to learn them if you just sit down and start typing a way... clearly, MS is optimizing for a minimal initial learning curve. If he'd rather use an application that forces use of structure-based layout, that's a personal preference, and I'm certainly not going to say that's wrong. But claiming that Word doesn't do it (and do it pretty easily) is wrong.

If you had read to the end of my post, you would have read the part where I make it clear I'm not defending Word across the board. It has a huge, rich set of problems to choose from if you want to bash it. But the original poster picked stupid things to complain about.

Re:"reasonable" to use version control with binary by jaoswald · 2002-01-10 11:27 · Score: 2

It can be reasonable to use version control with binary files.

I believe what you mean to say is

"is it reasonable to use version control when you give up the following benefits:

1) compact storage by using deltas
2) easy 'diff'-type comparison between versions
3) machine assistance in merging branches."

(1) these days is hardly noticeable.
(2) and (3) are, admittedly, the big problems.

The primary function of version control is to maintain a snapshot of files at multiple checkpoints. There doesn't have to be parseable data to do that.

Yes by Da+VinMan · 2002-01-10 11:31 · Score: 2

Thank you; that's what I meant. I regularly stick binaries away in VSS. I just don't expect it to do anything fancy with the binary for me.

--
Please mod this post only if you think others should/n't read this. I have enough ego^H^H^Hkarma. Thanks!

It depends... by dzeuthen · 2002-01-10 11:53 · Score: 2, Interesting

The word 'Documentation' as used in software engineering, is often used to characterize a number of different documents. Here are the different kind of documents I produce in my position as a lead tech in a software company:

1. Interface/API documentation: Here I normally generate latex from the C++/Java/C sources with DOC++ and publish it as PDF's. I could generate HTML but most of my collegues agree with me that printed documentation are nicer.

2. User Manuals: It varies. troff for man pages, Latex for hardcopies, M$ Word if nontechs has to edit/localize the stuff.

3. Tech Specifications, Software Design Documents: Such documents are mostly used within the company by the tech staff, so I use Latex for formatting and M$ Visio (and sometimes some fourth-generation tools such as Erwin or Rational Rose) for diagrams. It works for me! And these can be put under source control (we use CVS).

4. Collaborative documents: Such as proposals, RFPs, Site Acceptence Test documents that non-techies (Account and Project managers most of the time) has to edit.. For these I use M$ Word/Excel and I must admit I use a considerable amount of time on the things that LaTeX does automaticially for me - that is layout and presentation.

As a rule of thumb I always submit documents as PDFs. Good luck and always remember YMMV!!

Noweb, Latex Re: Literate Programming by buzz_mccool · 2002-01-10 12:01 · Score: 2, Informative

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

Re:PEBKAC by uebernewby · 2002-01-10 14:34 · Score: 2

So Powerpoint was too dumb to properly scale the JPEGs? Why am I not surprised...

In the same way that your browser is too dumb to scale down JPEG's even if you've explicitly stated in the code that you want them to do so once displayed? C'mon, this is just an example of a Stupid User Bug.

--

News and bla for computer musicians: http://lomechanik.net/

texinfo or docbook by runswithd6s · 2002-01-10 17:21 · Score: 3, Informative

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 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)); /* core dump */

Joe Average? Nah. by Grendel+Drago · 2002-01-10 18:02 · Score: 2

TeX was never meant to appeal to "Joe Average". Knuth says as much himself in the TeXbook. It's meant for producing technical manuscripts of the highest possible quality. For most tasks, MS Word will do the trick.

But for those of us who need kickass math functionality, are preparing a thesis, or are awed by the geek-factor, TeX is *it*.

TeX (and by this I mean LaTeX as well) is not meant to be used lightly. But for large, complex projects, its power and utility are evident. It simply scales much, much better than editors like Word.

Good for StarOffice if it wants to take over the office suite market. It's an important part of getting Linux on the desktop... but TeX is something utterly different.

And about the fonts... what is it you're trying to do? Do you have some TrueType fonts you want to use with TeX?

http://www.radamir.com/tex/ttf-tex.htm

It's nontrivial, but it certainly can be done...

-grendel drago

--
Laws do not persuade just because they threaten. --Seneca

HTMLDOC looks good, mod parents up by dublin · 2002-01-10 18:46 · Score: 2

I just had a look at the HTMLDOC docs (if that's not too redundant.)

This is absolutely killer. I've wanted something like this for years. HTML is not a layout format, but will do fine for most documents, but was lacking a few simple things to let it be a reasonable printable document format. HTMLDOC intelligently filters HTML into very presentable PS or PDF documents. (Look at the online docs for good examples...)

HTMLDOC adds the missing pieces! Margins, page breaks, duplexing, headers and footers, even the ability to define the order and options for each chapter in a book and be able to process them all at once.

This looks VERY good. If it works as advertised, I may be buying the supported version RSN. I'm impressed, and it takes a lot for software to impress me.

The fact that it's free and open source, too, is just icing on the cake...

--
"The future's good and the present is nothing to sneeze at." - Roblimo's last ./ post

LaTeX2HTML not a complete solution by ader · 2002-01-10 22:58 · Score: 2, Interesting

Be wary of grandiose claims for the power of LaTeX2HTML. Yes, it usually does a good job of converting simple to moderate LaTeX documents. However, once you start writing your own style files and using complex macros, it's a whole new ballgame. Theoretically, L2H can be extended to cope with any new macro, but you need Perl skills to do so and API documentation is poor-to-non-existent. Various obscure bugs may crop up from time to time, configuration for some odd situations (such as custom style files) can be non-intuitive, it's been in beta for years and releases are infrequent (although I notice that a new release came out in December).

It's not a bad program, but YMMV for actual use. (Note: I make my comments after writing a 100 page product manual in LaTeX.) OTOH, I must admit that a printed LaTeX document is a thing of beauty. If you're serious about using it, you definitely need to buy a book or two (say Lamport's and one more comprehensive reference).

If you're starting from scratch though, maybe you should give DocBook a proper go, given that it is supposed to be the format of the future and subsume all others.

Cheers,
Ade_
/

--
Big Bubbles (no troubles) - what sucks, who sucks and you suck

Interface vs implementation by Anonymous+Brave+Guy · 2002-01-11 01:34 · Score: 2

If you work for a libraries group (as I do), then it's important to define an interface, and get everyone (i.e. people who are gonna use the libs) to agree on this, prior to starting coding.

OK, I accept the need for fixed interfaces between different modules or programming teams to be documented. However, I would suggest that it's easier to spec the interface directly in the language you're using, via an interface class in an OO language, for example. This avoids any chance for misunderstandings between teams, as the language will typically enforce that interface. If you need "low level" documentation, just add comments as necessary to the interface spec. There is no need to duplicate this effort by copying everything into a design doc as well; just print the source code to your interface declaration.

--
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.

Re:PEBKAC by SnapShot · 2002-01-11 03:38 · Score: 2

Not to split hairs, but what you've described is not a crash. I'd call it sabotauge and place the responsibility squarely on your shoulders.

For all the literalists out there, the quote "If an application crashes, it's the developer's fault. Period. End of story. It is NEVER the user's fault" is the correct response to any developer including (especially) myself who says "well, no wonder it crashed, you weren't supposed to do 'x' you were supposed to do 'y'; I didn't program it to be able to do 'y'."

Part of being a good developer is anticipating and protecting against the "wrong" ways people are going to use your program. You protect against memory leaks and try to make sure all the files get closed if the user accidentially kicks the power cord out of the wall. In the absence of perfect programming (i.e. all software currently in existance) you try to get enough information to the user that he may try and recover from the error.

--
Waltz, nymph, for quick jigs vex Bud.

Re:PEBKAC by 3am · 2002-01-11 04:28 · Score: 2

sorry, i misread it. in any case, i'll stick to textpad whenever possible :)_

--

A: None. The Universe spins the bulb, and the Zen master merely stays out of the way.

Re:PEBKAC by Isofarro · 2002-01-11 04:53 · Score: 2, Interesting

look at the other comments. a lot of people have used word, and it's worked well for most of them. myself included.

I find word very cumbersome when trying to format documents correctly. Though earlier this week I found a cute way of formatting documents properly in Word:

I use a wiki for my own documentation - nice simple stuff like == 2nd Level Heading == and a few in-line HTML tags.

I then copied the htmlised text from IE5, pasted it straight into word - self formatted - looked like any other document we have here.

The bonus of this trick is that I've built myself a wiki to DocBook converter (partial at the moment), so my wiki is a neat document management system that I can use from any web browser.

I'm a big fan of wiki's - its a useful catch all solution

Re:PEBKAC by einhverfr · 2002-01-11 14:01 · Score: 2

Saying that it's the code's fault is like saying that automobiles should be built to withstand a 150 mph impact, afterall, it's not the operators fault that they drove at 150 MPH into a brick wall, the car should have been built to withstand it.

So, I suppose autos should not be designed with crashes in mind?

But a program crashing is not the same thing. For the most part, crashes happen because the program is trying to do something it is not allowed to do-- to follow your analogy, the car is driving itself into the brick wall. This usually occurs because the data is not being validated (not checking to see if the pointer is NULL, of if the data written is the same size as the data expected).

--

LedgerSMB: Open source Accounting/ERP

Re: TeXInfo is better than LaTeX by fireboy1919 · 2002-01-12 01:10 · Score: 2

LaTeX can output RTF (and by that token also MAN), HTML, DVI, PS, and PDF. As far as quality to effort, many organizations have already created formatting classes to produce the desired document format used by many groups of people (for instance, you can get IEEE format easily). BibTeX, which is used extremely frequently with LaTeX, also makes it easy to manage huge bibliography databases. Also, the Math formatting is absolutely spectacular, and I doubt it could get simpler without losing functionality (I don't know that this is true - tell me if you've found the opposite to be true).

What other formats are you looking for? And what do you mean, it has a higher output quality, and lower quality to effort ratio? You need to qualify that.

I think that perhaps you're talking about writing a man or info page. Perhaps an application specifically designed for that purpose is better at it than a general purpose application, but overall, I think that the reason so many more people are using LaTeX for documentation than texinfo is because of its usefulness.

--
Mod me down and I will become more powerful than you can possibly imagine!

156 of 583 comments (clear)