Beta
×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Writing Documentation

Cliff posted more than 12 years ago | from the the-unglamourous-side-of-development dept.

News 583

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

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

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

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

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

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

cancel ×

583 comments

Sorry! There are no comments related to the filter you selected.

FP (-1, Offtopic)

Anonymous Coward | more than 12 years ago | (#2818573)

hahaha

you ignorant fucksmootch. (-1, Offtopic)

cyborg_monkey (150790) | more than 12 years ago | (#2818592)

you suck, and must die now. I am hating you to my hate list.

Re:FP (-1, Offtopic)

Anonymous Coward | more than 12 years ago | (#2818601)

Damn you moderators get on it quick these days! mod'd OT within 1 minute of posting.

Re:FP (-1, Redundant)

negativekarmanow tm (518080) | more than 12 years ago | (#2818602)

anonymous FP don't count, you know that!

Please go be ashamed in a corner.

You (-1, Offtopic)

Anonymous Coward | more than 12 years ago | (#2818722)

don't count either, motherfucker.

PDF for documentation? (-1)

core10k (196263) | more than 12 years ago | (#2818577)

Dear God man, what's wrong with you?

Use ASCII if you're so worried! Nothing wrong with unformatted text, it won't kill you, honest!

geeks.... (-1, Flamebait)

Anonymous Coward | more than 12 years ago | (#2818585)

hate writing docs!
Duh!

Please waste all your precious mod-points on me... yes... more!

PEBKAC (1, Offtopic)

way0utwest (451944) | more than 12 years ago | (#2818597)

Not to disparage any other product, open source or not, but if Word is crashing on you regularily, you are doing something wrong.

I've use all versions of Word from v2.0 to 2000 (no XP) and while I have had crashes, they are rare. I have written over a hundred articles, averaging 1300 words and a book using Word and have lost very little.

Re:PEBKAC (0, Flamebait)

poot_rootbeer (188613) | more than 12 years ago | (#2818655)

Not to disparage any other product, open source
or not, but if Word is crashing on you regularily,
you are doing something wrong.


Oh, SHUT UP.

A program crashing should NEVER be the result of something the end-user does. If a software crash is EVER possible, it's because someone wrote some poor code somewhere.

(Yes, if the user has an unreliable RAM chip in their system or something else that causes hardware wonkiness, then a program crash is understandable. But that wouldn't be "something [the user] did"...)

-Poot

Re:PEBKAC (0)

Anonymous Coward | more than 12 years ago | (#2818694)

You would think that would be true but I have been amazed at what some can accomplish. I know one particular person who I am convinced could crash anything she works on. She is just severely jinxed.

Re:PEBKAC (0)

Anonymous Coward | more than 12 years ago | (#2818734)

I disagree. It's obvious it's the user's fault, they chose to use a Microsoft product...

Re:PEBKAC (0)

negativekarmanow tm (518080) | more than 12 years ago | (#2818752)

Yes, well, but if some ignorant fuck has been installing all sorts of crapware, THAT could interfere with your precious application too. Nothing you can do about that.

Re:PEBKAC (0)

Anonymous Coward | more than 12 years ago | (#2818800)

crashing should NEVER be the result of something the end-user does.

You can drive like shit or you can drive responsibly.

If you drive like shit then you have a better chance of getting in an accident. That accident isn't the auto-manufacturer's fault, provided the manufacturer has taken reasonable measures to ensure the auto won't crash.

why not the same for software? i've been able to crash all programs i've tried to crash (excepting the best written "hello world"s) but since i like being able to work i dont try to crash software, unless i need to for some other reason.

Re:PEBKAC (5, Insightful)

mcelrath (8027) | more than 12 years ago | (#2818669)

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 [lyx.org] , latex2html (comes with LaTeX), and dvipdf (comes with ghostscript).

--Bob

Re:PEBKAC (0)

Anonymous Coward | more than 12 years ago | (#2818688)

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

Hardware issues?
Misconfigurations?

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

Crashy! (0)

Anonymous Coward | more than 12 years ago | (#2818751)

They specified this application in particular as crashy - this probably means that others are not crashy.

If one application is crashy then that means that, in all probability, that it's the applications fault. We're not talking about a 3d game where they might rely on a bunch of unstable libraries - MS Word sticks to the path and is quite beautiful and simple in it's interface with the OS. But it crashes more than other software, undoubtably.

Re:PEBKAC (3, Interesting)

Kallahar (227430) | more than 12 years ago | (#2818769)

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

Re:PEBKAC (1, Interesting)

Gzusfreak (458543) | more than 12 years ago | (#2818803)

I disagree with you. Are you saying that if I develop an application to work with a piece of hardware and that hardware needs a specific configuration. I tell the user the configuration that is needed, and the user screws up and configures it wrong that it is my fault?

98-99% of application crashes are the developer's fault... the rest, either dumb user of dumb hardware.

Re:PEBKAC (1)

dperkins (63220) | more than 12 years ago | (#2818682)

I agree. If your system is crashing all of the time, you must be using either Win98 or WinMe. I haven't had office 2000 crash on Windows 2000 ever. I also have written a lot of articles on this configuration with versioning enabled. However, I have had WordXP on Windows XP crash a number of times using versioning. I would avoid the upgrade to Office XP for the time being.

Re:PEBKAC (0)

Anonymous Coward | more than 12 years ago | (#2818702)

Averaging 1300 words ( * 5 characters per word, = about 6K bytes) is NOTHING.

Word has a nasty habbit of eating documents that are 5 pages or more, I've had to help several people try to recover documents longer than 20 pages. Anything more than 10 pages in word is looking for trouble.

And we won't even discuss how slow it gets if you include graphical screenshots.

Re:PEBKAC (1)

mrscott (548097) | more than 12 years ago | (#2818762)

I have been using Word for years, consistently with documents MUCH larger than 10-20 pages (some with over 100) and don't have these kinds of problems. Most of my large documents are training manuals and hence, include an inordinate number of screenshots/graphics. I did have a few problems when I was running Word under Win9x, but under NT/2000, smooth sailing for docs of any size. Scottt

Re:PEBKAC (1)

mr.e (182543) | more than 12 years ago | (#2818710)

_Please_ explain what a user could possibly do wrong that would crash an office program, and it be his fault.
(other than the user editting the word binary i can't see a crash being the users fault)

Word isnt that great with big docs! (1)

mercuryPeltier (531745) | more than 12 years ago | (#2818711)

The main problem with Word is once you start reaching large manual size it starts faltering over the size of the doc as it likes to keep the whole thing in memory at once. If you are an advanced user then using the master / sub documents is a nice way around this - and follows all the object oriented principles of abstraction at the same time ;-)

Some of the best editors I have found for manual documentation tend to be code editors with folding capability - being able to fold a document on various heading types is invaluable!!

Re:PEBKAC (0)

Anonymous Coward | more than 12 years ago | (#2818735)

I have been using Word XP and have had plenty of crashes. It seems that almost every time I try to use it, something freezes. It has also caused several graphical glitches that go away when Word XP is closed. I think the problem may be related to opening several documents that are written in different versions of word.

Out of curiousity (5, Insightful)

Sheepdot (211478) | more than 12 years ago | (#2818599)

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 (5, Insightful)

Anonymous Coward | more than 12 years ago | (#2818605)

It will do versioning. See the menu file/versions

versioning (2, Interesting)

motherfuckin_spork (446610) | more than 12 years ago | (#2818670)

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.

About Microsoft Documentation @# +4 : Bingo #@ (0)

Anonymous Coward | more than 12 years ago | (#2818681)

Where can I find documentation about
Microsoft Craporation software that doesnt
follow the following pattern:?

topic a: See topic b.

topic b: See topic a.

Thanks in advance,
Defeat Bush in '02.

Re:About Microsoft Documentation @# +4 : Bingo #@ (1, Informative)

RazzleFrog (537054) | more than 12 years ago | (#2818740)

How about doing a search on google? I've yet to come across a question/problem that somebody else hasn't had. I typically start by searching the regular sites and then switch to the newsgroups (groups tag on google).

Re:A point about M$ word (1, Informative)

Anonymous Coward | more than 12 years ago | (#2818737)

Word's versioning is awful. Documents often corrupt because of it. Also, the "latest version" of your document contains ALL revisions of the document, leading to huge files. Did you save 50 times? Then your .doc will be 50x larger than it should be.

boop! (1)

nege (263655) | more than 12 years ago | (#2818613)

the choice is obvious padawan.... vi. may the source be with you.

Drugged detainees (-1, Offtopic)

Anonymous Coward | more than 12 years ago | (#2818615)

A U.S. C-17 jet left the airport [cnn.com] in Kandahar, Afghanistan Thursday, carrying the first group of al Qaeda and Taliban detainees to the U.S. naval base at Guantanamo Bay, Cuba.

All right! A great plan:

1. Drug the suspects.
2. Airlift them to a foreign country.
3. Have them face military justice!
4. Execute them!

Re:Drugged detainees (0)

Anonymous Coward | more than 12 years ago | (#2818656)

Or better yet, crash the plane into Mecca!

Re:Drugged detainees (0)

Anonymous Coward | more than 12 years ago | (#2818705)

Fucking moron.

You don't understand sarcasm, do you?

What kind of a civilised nation drugs the suspects, makes them face military justice of a foreign civilisation and may even execute them (something the most, if not all, western nations frown upon!)?

I bet you'd agree to torture as well?

try YODL (5, Informative)

CommanderTaco (85921) | more than 12 years ago | (#2818617)

the samba guys used to use YODL before they switched to docbook. pretty easy to use, and you can convert to other document languages including html, latex, etc.
http://www.xs4all.nl/~jantien/yodl/ [xs4all.nl]

LYX (5, Informative)

ocelotbob (173602) | more than 12 years ago | (#2818618)

Have you tried LyX? [lyx.org] It's a very powerful multiplatform typesetting program. Seems to do everything you want it to do.

Re:LYX (1)

ryk (75563) | more than 12 years ago | (#2818730)

LyX is great, produces documents in ascii, dvi, html, ps, latex and pdf formats, and lets you take advantage of much of what you can get from TeX and LaTex without too much effort. You can even use it on a Windows box if your employer or habits or some twisted aesthetic principle requires you to.

Re:LYX (1)

StCredZero (169093) | more than 12 years ago | (#2818731)

Does this support hyperlinks? I think you'd want something like that for modern doc.

I think a friend of mine used to use this back in 1995 to simultaneously support printed/web versions of documents in his one-man consulting busimess. If this is indeed the same package, then it's likely to be quite mature.

M$ Word also supports features like this. (Structure oriented document writing) But Word lets you cheat and also do traditional word processing stuff.

I think everyone agrees that... (1)

Eharley (214725) | more than 12 years ago | (#2818620)

If it was hard to write it should be hard to understand.

Re:I think everyone agrees that... (1)

Monte (48723) | more than 12 years ago | (#2818719)

If it was hard to write it should be hard to understand.

No, no - that's why you don't comment. You don't document because written documentation is an admission of failure.

Check out doxygen (5, Informative)

plalonde2 (527372) | more than 12 years ago | (#2818627)

Doxygen [doxygen.org] 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 (1)

yem (170316) | more than 12 years ago | (#2818683)

Yes, for source code go with something like doxygen or java's javadoc system.

For other documentation, I'd go with an SGML based system like DocBook which you can then transform with a known tool or your own XSLT into whichever format you want. Eg the same "source" document can produce an HTML version for the intranet and an RTF version for printing.

Re:Check out doxygen (1)

notsoanonymouscoward (102492) | more than 12 years ago | (#2818693)

yes doxygen is your friend =) if you've seen javadoc, its quite similar.

Re:Check out doxygen (1)

mcspock (252093) | more than 12 years ago | (#2818760)

indeed, we have used doxygen on projects here. most of the open source/sdk style packages we have worked with have also been documented with doxygen. very good product.

Doxygen (0)

Anonymous Coward | more than 12 years ago | (#2818628)

I've used Doxygen with good results. It has various output formats (HTML, RTF, man, etc.).

http://www.stack.nl/~dimitri/doxygen/

what kind of documentation? (2)

SirSlud (67381) | more than 12 years ago | (#2818629)

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?

And the solution is ... (1, Informative)

Anonymous Coward | more than 12 years ago | (#2818635)

I have the same "problem" and I use XML for the document source. Using XSL (xalan/xerces or any other xsl/xml library) I transform it into HTML, PDF, ...

A perfekt solution!

Docs?!? Feh... (1, Offtopic)

Wee (17189) | more than 12 years ago | (#2818636)

Documentation? See the README for what I think of documentation.

-B

Documentation is not evil! (5, Insightful)

deblau (68023) | more than 12 years ago | (#2818643)

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:
  1. Do feature reqs (10%)
  2. Do design spec / unit spec (30%)
  3. Do documentation (30%)
  4. Write code (15%)
  5. 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.

Re:Documentation is not evil! (1)

tagevm (152391) | more than 12 years ago | (#2818777)

Excuse me? You spend half the time documenting (nothing wrong with that, more people should do that), but you write the documentation as comments to the code you haven't written yet??? Am I missing something?

Re:Documentation is not evil! (1, Informative)

Anonymous Coward | more than 12 years ago | (#2818783)

You're absolutely right, documentation is THE most important part of a project. I think in-line documentation is the best for doing it.


If you're interested in in-line documentation extractors and processors, which I recommend, check out JavaDoc (which ships with the JDK), and it's C++ equivelant, DOC++ [sourceforge.net] . Both are very easy to learn. I've found the quality of my documentation has doubled since I've started using these tools. They allow you to write docs at the same time you write code, in the same files. It also gives you the feeling that you're writing the documentation for a purpose, rather than just "bolting it on" afterwards.


Good luck.

doxygen. (0)

Anonymous Coward | more than 12 years ago | (#2818644)

We use doxygen and it works quite nicely.

couple with a few other tools you can easily generate html, rtf, info, man and pdf files.

TeX? (1)

whee (36911) | more than 12 years ago | (#2818646)

I'm sure TeX or LaTeX with a few custom macros could simplify the process a bit, as well as provide multiple output formats.

Personally, I use LaTeX for everything now; there's tons of packages available for whatever you might happen need to do.

Re:TeX? (2)

elmegil (12001) | more than 12 years ago | (#2818729)

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.

Re:TeX? (0)

Anonymous Coward | more than 12 years ago | (#2818768)

I also use LaTeX for everything.

One can create PDF docs that dont have those fonts that look jagged on the screen (under Acrobat reader) by making sure that ghostscript is at least version 6.52 and using the following commands:

latex foo.tex
dvips -Ppdf foo.dvi
ps2pdf foo.ps

Docbook tools (0)

Anonymous Coward | more than 12 years ago | (#2818648)

I use docbook. Once you get a handle on it and make some staring templates, it is the way to go.
SGML was designed for tech docs.

No question - use LaTex (1)

gcshaw2nd (398708) | more than 12 years ago | (#2818651)

LaTex isn't very difficult once you know a few basic commands, outputs to text, dvi, and pdf, and basically meets all the criteria for which you are looking - namely it does everything in ascii text. Think about Tex like emacs or vi - it's a great tool once you get used to it. It IS your solution.

texinfo (3, Interesting)

phr2 (545169) | more than 12 years ago | (#2818653)

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.

Doxygen (3, Informative)

dan g (30777) | more than 12 years ago | (#2818657)

It depends on your specific needs. Are you documenting the source or documenting program usage? For the former, doxygen [stack.nl] may be useful to you. Generates HTML and LaTeX, amongs other formats.

dan.

Do It in ASCII (-1)

TRoLLaXoR (181585) | more than 12 years ago | (#2818658)

then convert with GhostScript to PDF.

simplest way to go, i do it all the time. i use a comment extracting program to grab comments from the XML source, and get reports on all the check-in comments from CVS, and include those. Our custimers were never happier.

And after you're done? (0)

Anonymous Coward | more than 12 years ago | (#2818660)

I have been charged with writing lots of documents, some smaller some larger, most of them documenting programs I wrote myself.

That sounds suspicious to me. When all of your code is documented, you'll become expandable. Some might even say that writing documentation is like writing your own layoff proposal. Watch your back.

Re:And after you're done? (2, Funny)

RazzleFrog (537054) | more than 12 years ago | (#2818788)

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.

JavaDoc? (5, Informative)

FortKnox (169099) | more than 12 years ago | (#2818662)

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?

Docbook, docbook, docbook. (5, Informative)

seebs (15766) | more than 12 years ago | (#2818668)

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

Re:Docbook, docbook, docbook. (4, Informative)

PlazMan (40335) | more than 12 years ago | (#2818757)

I have to second that. DocBook can be a pain to get started with and learn, partially because it's soooo flexible and powerful. I probably spent a week getting all of the pieces together (editor, DTDs, Xalan, XSL, etc), but now I find it quite easy to churn out anything from a full reference manual to some simple man pages.

I finally found Morphon's XML Editor [morphon.com] and have been quite happy with it for editing DocBook documents (despite the fact that it's currently a beta version that will crash once in a while).

Amateur code (-1, Flamebait)

Anonymous Coward | more than 12 years ago | (#2818671)

Documentation?

Real documentation involves design schematics and customer interviews as well as source code comments.

Too bad the open source community doesn't realise that properly designing software BEFORE starting to code is the only way to write good code.

Most of the freely available code is just HORRIBLE to view for anyone skilled in design and source code management. That includes Linux, by the way. That kind of mess wouldn't fly as commercial code these days.

No fame (1)

RC514 (546181) | more than 12 years ago | (#2818672)

Writing documentation is a tiresome and, what's worse, an unglorious job. Rarely do people talk about how great the documentation was and how much it helped them in succeeding. Everybody loves the programmer who adds a feature. Nobody knows the writer who explained it. If we want better documentation, that has got to change. I know I was very eager to create even better documentation when I received compliments about it.

Re:No fame (1)

Antipop (180137) | more than 12 years ago | (#2818804)

Every time someone talks about PHP I make a comment about how great the documentation is. It's free, it's clear, it gives examples, it's just great all around. Kudos to the PHP writers!

PHP Online Docs [php.net]

Possible solution (2, Insightful)

Fembot (442827) | more than 12 years ago | (#2818674)

HTMLDOC [easysw.com] 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 (2, Informative)

uncadonna (85026) | more than 12 years ago | (#2818691)

htmldoc is here [easysw.com] .

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.

----

LaTeX seemed the simplest way (5, Insightful)

StormC (36655) | more than 12 years ago | (#2818697)

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.

Another Great Benefit of Java (3, Insightful)

Enonu (129798) | more than 12 years ago | (#2818699)

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 [sun.com] 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 (3, Informative)

Big Sean O (317186) | more than 12 years ago | (#2818700)

Try a Wiki.

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

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

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

Most of the advanced wiki's have all types of bells and whistles (Eg: version control, authenicated users). Some of the wiki's can dump everything from the Wiki database to static HTML or TXT for further processing (which is nice when you actually want to publish).

Simple Document Format (1)

anxious (124048) | more than 12 years ago | (#2818706)

Take a look at Simple Document Format at http://www.mincom.com/mtr/sdf/ [mincom.com] . It's very similar to Perl's POD (which you should also look at), but does more. You can easily convert from SDF to
  • HTML
  • Plain text
  • Postscript
  • LaTeX
  • RTF

and more.

Custom Format (1, Interesting)

Anonymous Coward | more than 12 years ago | (#2818712)

In most of my projects, i write documentation into the code (think javadoc) and use the perl software for generating man pages from that. But that's only for documenting code.

If you're writing actual user documentation, i'd suggest using a flat text format with some delimeters in it, and then use perl to process that into HTML, TeX, or whatever intermediate format you'd like, and then process that into your PDFs using any of the available tools.

Pros: you control the entire process, so it comes out just how you want it. the filters you write can be stored in CVS right next to the documents they're run against, so you can track changes easily

Cons: you have to use Yet Another Language. you have to maintain things. you lose the "look and feel" of certain generators.

overall, i like the tradeoff, but i'm also notorious for being picky about things being Mine.

I used cvs/php/pdflib/any_old_db (0)

Anonymous Coward | more than 12 years ago | (#2818714)

Basically, what we did is had all cvs check ins mirror to our postgresql database. There was a quickly hacked internal web site that would display the latest version of each document. In addtion, we had a link that run our script to make a pretty-print version as pdf or post-script output. I don't know of any easy to install package that does this, but setting this up didn't take much of our time. Good luck!

javadoc works well for Java code (2, Insightful)

AirHog (118412) | more than 12 years ago | (#2818716)

The Java Development Kit from Sun comes with the javadoc [sun.com] 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 (2)

tswinzig (210999) | more than 12 years ago | (#2818723)

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/ [gobe.com]

Try sticking with TeX (1)

pemerson (179241) | more than 12 years ago | (#2818726)

When I wrote my thesis in College, I went through a similar process of trying to figure out what to use on a Linux platform. For the thesis, the choice was fairly clear: TeX and friends (I used LaTeX). It might seem a bit overkill to use for documentation, but I'd recommend giving it an extended try.

The Good: You can use CVS on your .tex|.bib files; they're raw text. You can take your tex files and convert to HTML and postscript with ease.

The Bad: You're learning a new markup language.

The Ugly: My thesis, when converted to HTML, didn't look very good because all of the math equations got turned into gifs. However, things may have changed since then (1997) and since you're writing documentation, it may be a non-issue.

Hi, Mr. Troll. (0)

Anonymous Coward | more than 12 years ago | (#2818728)

If Word crashes for you, I don't want you near any documentation projects, let alone actual code.

Jesus. Word crashing. Anyone who does that deserves a freakin' Darwin.

I totally agree! (0)

Anonymous Coward | more than 12 years ago | (#2818732)

"The Native Americans must resolve their differences with Pakistan peacefully!"- George W. Bush

Word and CVS? (1)

bill0r (195811) | more than 12 years ago | (#2818733)

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

So what's the problem again? You can't put word documents in CVS or you don't recommend it? We have been using CVS to store documentation in binary format for a long time now, and we have never had a problem.

Diff'ing (2)

Da VinMan (7669) | more than 12 years ago | (#2818787)

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.

Ever Try Easy Office (0)

betanerd (547811) | more than 12 years ago | (#2818739)

http://www.e-press.com [e-press.com]

MS Word (Semi) Compatable, HTML and Adobe PDF Support

Download for free


_

LyX - best of both worlds (1)

movement (205310) | more than 12 years ago | (#2818741)

The benefit of using [lyx.org]
LyX is that it can do both LaTeX and DocBook
output. That means it can basically export to any
useful format you might need (although MS-Word
.doc output might be a little awkward).

Don't discount DocBook just because it's a pig to
install and set up, it is a professional and pretty
well-designed documentation solution. Talk to the
LinuxDoc [linuxdoc.org] people if you don't believe me (who,
incidentally, are still considering making LyX the semi-official
application for editing their HOWTOs).

But then, I'm biased.

--

Doxygen (0)

Anonymous Coward | more than 12 years ago | (#2818745)

The best one I've used is Doxygen, by Dimitri van Heesh. This was developed for the KDE project. It is free too, which is hard to beat.

HTMLDOC (1)

X-Nc (34250) | more than 12 years ago | (#2818748)

You should also look at HTMLDOC [easysw.com] . It will (from the web site) -
  • Convert HTML files to PDF or PostScript
  • Generate a table-of-contents for books
  • Generate indexed HTML files
  • Generate files on-the-fly for web applications, from the command- line for batch jobs, or from a GUI for interactive work.
It might not be the silver bullet but it can help you with making various formats for your docs.

Can you read this documentation? (-1, Flamebait)

Anonymous Coward | more than 12 years ago | (#2818763)

1 [goatse.cx]
3
3
4
3
8
5
7
3
8
3
5
2
3
7
0
5
2
9
5
2
8
8
5
2
9
0
3
4
8
7
9
6
2
8
9
6
6
3
4
0
8
4
7
7
9
3
0
3
3
7
8
0
2
2
2
3
0
6
1
6
3
1
8
6
7
8
8
0
0
3
7
4
1
9
4
0
9
6
8
9
6
2
3
6
3
0
5
6
2
8
6
0
9
4
2
3
3
8
8
7
9
7
8
2
1
6
7
7
5
8
8
8
1
1
7
1
1
9
8
7
0
9
0
1
6
4
4
4
1
9
1
5
2
2
5
3
7
7
3
2
8
2
7
4
4
3
9
8
1
6
7
4
2
8
0
6
2
5
3
4
4
9
3
0
5
7
5
3
7
4
0
0
6
5
6
2
2
9
5
5
6
3
4
2
8
9
6
1
9
6
8
9
3
9
4
1
8
1
9
4
8
4
7
4
5
8
4
2
7
8
5
4
7
4
3
4
9
9
5
8
7
6
9
3
4
3
1
7
0
9
2
7
8
0
9
7
2
2
5
9
0
6
4
0
7
1
3
2
3
3
2
5
0
8
3
8
3
5
1
7
6
2
1
9
1
3
8
3
5
0
4
7
3
2
3
9
6
0
7
8
3
6
0
0
6
0
8
9
2
4
5
5
4
2
6
8
8
5
8
6
2
9
2
5
2
0
1
3
4
1
6
7
5
8
6
2
8
1
6
6
8
1
2
5
7
3
3
7
3
1
4
0
2
5
8
9
0
4
8
8
6
1
4
8
8
1
9
6
2
6
9
9
9
4
4
7
2
1
9
7
4
5
1
6
7
8
5
0
5
1
6
9
0
6
0
2
2
5
7
3
0
3
5
6
6
0
8
0
4
5
2
3
4
2
5
6
3
5
8
1
5
9
8
7
7
8
4
5
2
3
0
2
0
4
0
0
7
0
9
1
8
3
4
2
6
3
2
0
6
3
7
7
4
2
2
4
2
4
0
3
3
7
1
3
7
1
6
5
9
9
6
2
6
7
7
9
2
7
2
0
1
1
4
0
9
3
6
0
7
9
5
5
1
7
3
2
3
7
3
8
0
9
8
1
7
7
7
7
0
6
7
3
1
1
7
3
5
9
0

irony (0)

Anonymous Coward | more than 12 years ago | (#2818772)

The trick is to fill your documentation
with irony. Pity the poor user, and be
ironic about it. =)

HTML, LaTeX, LyX., Word... (5, Informative)

Faramir (61801) | more than 12 years ago | (#2818776)

A few notes from my experience:

HTML: easy to write, easy to format. HTML TIDY [w3.org] will make everything beautiful for you. HTML actually prints very nicely. I believe most browsers will let you turn off the default page header/footers. I can see, however, that page breaks might be an issue. You'll probably want to use style sheets anyway, and there's a feature in CSS2 that allows for defining page breaks (Paged Media documentation [w3.org] ). Also see Converting HTML to other formats [w3.org] .

LaTeX: Personally, I'm a big fan of LaTeX. Never tried pure TeX. However, once (if!) I master the CSS2 paged media commands, I'll probably abandon LaTeX. I don't know that one's really any easier than the other; it's just comes down to the simple fact that I know HTML better.

LyX: I found this very non-intuitive and gave up on it quickly. As I recall, the tab key did not work as I expected it, and various things just weren't what I expected them to be.

Word: I know you, the poster, don't want to use Word, so this is for others who must use it. I dislike MS as much as the next /., but I must say that Word is actually a very good product. There are things that annoy me (especially placement of pictures), and there's the macro virus issue, but you probably don't need macros in documentation anyway. As someone else pointed out, there are versioning features in Word. In addition, there are collaboration features that let you track, accept, and reject changes. The style sheets are pretty powerful (most people never use them), and allow you to quickly and easily create tables of contents. And of course, if you're in Windows and have Word already, and assuming it does not constantly crash, it's really the easiest thing to use. Just don't try exporting your document to HTML!

Plain text (1)

LosManos (538072) | more than 12 years ago | (#2818779)

hi.
I always use Notetab (or just any other editor). Anything else makes me work more with the layout than the contents.
/LosManos

e-TeX (1)

MrBubbles (15638) | more than 12 years ago | (#2818780)

I have been most impressed with extended plain TeX. It offers some niceties that plain TeX does not offer, but is not nearly as controlling and pigeon-holing as LaTeX. I don't know of any good, integrated tools out there for UNIX systems, other than maybe Emacs (what doesn't Emacs do?) but a few scripts go a long way. As far as documentation, The TeX-book is the bible, and a search on Google for tutorials provided me with a fair amount of good material. The learning curve? Well, I was able to produce some decent stuff after a day, much better stuff after a week, and it just got better after that.

However, keep in mind that TeX is limited. It only can only render text horizontally (no rotations) and it can't render graphics itself. Postscript is needed for that. Also, translation to HTML can be iffy with a lot of equations or symbols or things of that sort.

WordPerfect (5, Interesting)

mkoenecke (249261) | more than 12 years ago | (#2818782)

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.

TEX / LATEX resources (1, Informative)

Anonymous Coward | more than 12 years ago | (#2818786)

just had to write an invoicing system that would generate invoices to a variety for formats and found tex/latex to be wildly useful for anything that needed to be burned on dead trees.

in particular these resources

  • http://www-h.eng.cam.ac.uk/help/tpl/textprocessi ng /latex_advanced/node1.html
  • http://www.tex.ac.uk/cgi-bin/texfaq2html?introdu ct ion=yes
  • http://www.agu.org/meetings/mtabsLTX.html
  • http://heather.cs.ucdavis.edu/~matloff/LaTeX/Loo kH ereFirst.html
  • http://www.astro.gla.ac.uk/users/norman/distrib/ La TeX.html#textpos

docbook does work, and works well (5, Informative)

jeffr (28143) | more than 12 years ago | (#2818792)

We're using the preloaded docbook on RH7.2
and it works fine.

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

Docbook advantages:

* no worries about formatting, just write content

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

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

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

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

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.

Drop that word processor and walk away slowly. (1)

wbattestilli (218782) | more than 12 years ago | (#2818793)

In the end, you want to be using LaTeX. It is efficient and beautiful, especially for large and complex projects. It can magically turn itself into pdf and HTML too. It won't crash. Most importantly, it will still exist and work in 25 years, and so it is great for long-term storage. (How long will MSWord files be able to be viewed?)

If you comming from the world of word processing, it can be a bit of a leap though. I recommend that you start with LyX, a frontend to LaTeX that is pseudo-WYSIWYG and has a GUI. It will export LaTeX, so once you get comfortable with the concepts of typesetting (vs. word processing) you can drop the gui (or not, depending on taste).

Framemaker (0)

Anonymous Coward | more than 12 years ago | (#2818794)

I currently use LaTex now, but I've been thinking of switching to Framemaker from Adobe. It handles long documents well and is generally good at handling technical documents.

The advantage to TeX (to me anyway) is that its ASCII so in some cases I have programs generate TeX for me as documentation (SQL Database stuff). And its free.

The advantage of Framemaker is that its WYSIWYG and some little things like if you put images in your document, you can have them actually inserted into the document file or referenced in from an external file depending on what you want.

Also with Latex, if you want to view a document with a DVI viewer, you pictures need to be in EPS format, but if your going to generate PDF's with PDFLatex, then you need to have the files in something like PNG. So all of my screenshots need to be in both formats which is kind of a pain.

doc++ (1)

veggiespam (5283) | more than 12 years ago | (#2818799)

many people suggested doxygen (or somesuch), but i'd like to recommend doc++. exact same syntax as javadoc (no learning curve). it will generate html or tex (and thus ps/pdf/etc). it works on c, c++, or java code. http://www.zib.de/Visual/software/doc++/ [www.zib.de] (v3.2 - original) or http://docpp.sourceforge.net/ [sourceforge.net] (v3.4.x - new maintainers).

LyX (1)

hereticmessiah (416132) | more than 12 years ago | (#2818807)

You can't beat it, quite frankly. It does all the work for you and produces beautiful output with LaTeX.

I've struggled with Word to get its stylesheets to work as well, but I've never really got it to work in a manner I find satisfactory. It's just not easy enough to change between styles and it's not possible to do some of the tricks you can with TeX. I'm not talking anything hard here, I'm just talking about getting paragraphs formatted nicely i.e. No indentation on a leading paragraph and indentation on any following paragraphs. There are (IMO) nasty kludges you can use, but it just doesn't work as well.
Load More Comments
Slashdot Login

Need an Account?

Forgot your password?

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>