views:

899

answers:

24

As a developer I really don't like writing documentation but when I have to I'd like to make the process as painless as possible.

The problem with Word is that it constantly gets in my way. I worry more about the layout than about the actual content ... that's why I'd like to get rid of Word.

Ideally I'd like to write my content and then 'compile' it into a document.

I've heard of LaTeX but I don't have any experience with it whatsoever. Would this be the right technology for the job? What editor (Windows) should I use? Is it a good idea to start with LyX?

EDIT: I'm not asking about documenting code (I use Sandcastle for that).

+2  A: 

What about using HTML? This way you could then publish the documentation if there will be need for many people to access it from many places.

User
+8  A: 

You could write your documentation using your own XML format and then transform it into any format with XSL (e.g. PDF via FOP+XSL-FO ). See also the DocBook XML format.

Pierre
DocBook looks promising! I'll check if I can get to tools to run on Windows. Thanks!
chris
+1 I consider docbook is easier than tex. Just because as a developer I know xml/xsd/xslt anyway.
schoetbi
A: 

The short answer is open office

It depends what do you want to do.

Are you writing scientific articles? Depending on the area many scientist prefer LaTeX.

Are you going to write a book? Think about docbook.

Luixv
The only argument for Open Office is that it's free. From a usability point of view, it is similar to MS Office.
mouviciel
Having used Open Offic a bit in the last year for work purposes, I came to the conclusion that none of the developers ever did any serious usability testing, and left it at that.
1800 INFORMATION
similar or worse. At least MS Office performs better.
Ionuț G. Stan
He says that Word is evil because "constantly get's in your way" so OpenOffice-Writer is evil aswell.
ktulur
@mouviciel: I find Open Office's usability much worse than MS Office's. If I had money, I'd buy MS Office.
Daniel Daranas
I agree with the rest of the commenters I'm afraid - OpenOffice is very clunky compared to MS Office
MrZebra
+10  A: 

I've found that wikis can be good for this. Find a wiki you like that lets you do a bit of formatting, but nothing really heavy. Ideally it should let you format code easily too - to be honest, the markdown available on SO is probably a good start.

That way:

  • You have change tracking built-in (assuming a decent wiki)
  • You can edit from anywhere
  • Everyone always sees the same documentation (instant distribution)
  • You can concentrate on content instead of formatting
Jon Skeet
What about printed documentation? Do wikis provide "printer-friendly" options?
mouviciel
I've tried this a couple of time and I usually run into problems when I need to share the wiki. Sometimes it needs to be printed and sometimes people just want in the form of a document. The wikis I've used didnt really support this.
willcodejavaforfood
Several wikis provide good print and export options. We use Confluence in my current project, but there are great open source options out there as well. I have to agree with Jon, Wikis are great for documentation (in addition to automatically generated documentation like javadoc).
neu242
Downvoters: please provide reasons.
Jon Skeet
Jon: I'm an upvoter that will suggest that half of the downvotes you receive (generally, not just for this answer) are out of envy. We all wish we knew half as much as you do.
FarmBoy
A: 

Depends on the documentation. I compile my source code documentation by writing 'good' inline documentation in the code and extracting it with PhpDocumenter (or in c# its an default build option to generate an documentation.xml file).

I never really bother with layout in other documentation, because i only use paragraphs for information and headings 1,2,3 for nesting information relationally. Then you can easily generate the TOC from this information. More designing this document only distracts from the contents.

Other projects at my company use an Wiki for the documentation because of the easy editing and version control.

Mark
+5  A: 

LaTeX is an extremely powerful tool and might well be overkill here as it is designed for scientific/mathematical literature. It has a (relatively) steep learning curve and can be tricky to coax to do exactly as you want if you're new to it. I LOVE LaTeX, but it is not really a general purpose word processor.

Have you considered OpenOffice instead?

Colin Desmond
"tricky to coax to do exactly as you want if you're new to it" is exactly as I would describe all "WYSIWYG" word processors. The main point for LaTeX is, in my opinion, reproducibility. When you have solved something, you can just look up how you did it when you encounter a similar situation next time.
Svante
A: 

Read this book: http://en.wikipedia.org/wiki/The_Pragmatic_Programmer . There is some idee fixe inside, so that documentation should be built automatically. Think about using your IDE for this, or look for some additional tools. Most modern languages support generating documentation as you write the code. This can simply maintain your doc in touch with latest changes in the code.

smok1
+2  A: 

Despite all efforts and reasonable expectation I don't think Word Processing has been "solved" yet.

My response to what I also personally find a deeply frustrating experience with MS Word is to avoid it altogether and use an auto-documenting tool like GhostDoc to generate XML from what I've already written in the code (DRY!) and deal with the XML from an XSLT based intranet site or similar later.

annakata
+21  A: 

My solution to this was to invest some time in creating a decent Word Template for myself.

The important thing to do is make sure you have a Style defined for everything you can put in the document.

Once you have all the Styles defined and all of the document content tagged with the correct Style instead of formatted in an ad hoc fashion, you'll be surprised how easy it is to produce good looking Word documents quickly every time.

The wider problem here is that everyone spends hours in Word and yet it is very rare for companies to invest in Word training. At some point you have to bite the bullet and take the time to teach yourself how to use it properly, just like you would with any other tool.

Dave Webb
Agreed - the key to efficient working in Word is to start with a good template and set of paragraph styles.Using the latest version with all service packs also helps. I recall a number of niggly issues when Word 2003 came out that were corrected with service packs.
Richard Ev
And in addition, assign shortcut keys to the most frequently used styles. I have ctrl-0 for text body, ctrl-1 for heading 1, ctrl-2 for heading 2... etc. Works very efficient.
Rabarberski
This is the approach I use too, although I use OpenOffice Writer instead of MS Word. The Stylist and Navigator features are very nice (I expect Word has similar features)
David Dorward
Seconded, if you have a suitable set of styles and remember to use headings (levels) appropriately then word will do most of the work for you - and you then get the benefits that go with.This is true for any Word Processing package - do everything with templates and styles and it becomes easy (once you've gone through the initial pain of getting them set up right).
Murph
I also heard that when you start with a template, you can produce nice documents. What happens when you want to change the template afterwards, though?
Svante
@Svante - I believe if the template is attached "properly" to document the document will reflect the changes. Otherwise you can reapply the template to the document to get the changes. This will only work if you've be careful to set Styles properly.
Dave Webb
"rare for companies to invest in Word training" This is the key, know or learn how to use it, you'll need to do the same for any other documentation tool.
Bratch
On this note, Words "Outline View" is invaluable for getting document structure right without worrying overly about how it looks whilst doing so.
Rob
+2  A: 

Are you talking about documenting your actual code? If so, I recommend Doxygen for unmanaged code and Sandcastle for managed code. Both will compile your help or build it as a website for you.

Both applications will read special tags above functions / classes / variables and compile that into the help.

Mark Ingram
A: 

You may want to look into doxygen at http://www.stack.nl/~dimitri/doxygen/, see their nice examples. In this case, the documentation is presented by tags in comments in the source.

Another option would be to use an online system like trac from http://trac.edgewall.org/ which is a wiki/doc/issuetracking system that lives on top of subversion.

Posipiet
A: 

I prefer to use a RTF editor which is a lot less clunkier than words. This way the formatting and all the headers/footers nonsense will not take up half your time. Wordpad has worked for me on several occasions. I'm stuck with Word for now though :(

willcodejavaforfood
A: 

there are a lot of possible ways:

  • embedded documentation, e.g. javadoc: good for describing APIs, not so good for the "big picture"
  • plain html: can be checked in under version control, a definite plus
  • a wiki, e.g. confluence -- great for collaboration, but has version control different from your source
  • LaTeX or somesuch: better suited for books or papers than typical documentation; support for graphics is cumbersome
  • an Office clone, e.g. OpenOffice: mostly the same as Word+Visio, but open source, with a nicer document format

I usually document the software structure (the "metaphors" of a project, component interrelations, external systems) up front, using Visio, in "freeform" UML. These are then embedded in confluence, which can be converted to PDF if someone wants a printout.

mfx
+21  A: 

Anything you can do with LyX you can do with LaTeX. LaTeX is suitable for all sorts of things; it has been used for everything from manuals to lecture slides to novels.

I think LaTeX is probably worth looking into as an option; if you've ever wanted to "code" for your word processor, LaTeX is for you. At the simplest level you can define new commands to do things for you, but there's a lot of power there. And the output looks really neat.

In my opinion, LyX is fantastic in certain circumstances, handy in others, and occasionally just gets in your way. I think it should be seen as a productivity booster for LaTeX. In other words, learn to use LaTeX before trying LyX. Both are of course free and available for Windows, though the learning curve is quite steep compared with MS Word. For long documents, or plenty of similar documents, LaTeX/LyX is probably a worthwhile investment.

Artelius
I think that the learning curve to produce _quality_ output is higher in Word.
Svante
+1 for LaTeX, it's a perfect match for what the OP wants to do. (Although, it's optimized for math, not for code... still probably worth a try.)
David Zaslavsky
+2  A: 

I considered a wiki, but I decided to go with a modified Markdown notation, for the simple reason, that a wiki's content isn't easily exported and distributed outside of the wiki itself, while the Markdown can be rendered into HTML.

Answer to chris' question about my workflow: I write the documentation with a Notepad-like application (TextWrangler, only because of its word-wrapping feature) in its raw Markdown format. Then I have a small localhost documentation website with my modified Markdown parser (extended for a few features and a bit more HTML-oriented functionality) that checks for the timestamps for the documentation files - if a file has been updated, it parses that file into HTML, and stores the file in a cache.

This way I'm able to edit the source documentation on my desktop, and just press F5 in my browser to see the results immediately.

Henrik Paul
Do you use this with a specific tool?
chris
+2  A: 

Well I've never found anything wrong with MS-Word in the first place. (i.e if you take the time to know how to use it effectively). OpenOffice indeed is an amazing & credible free alternative - but then if you hate MS Word for layout related problems, the same problem is gonna occur with OpenOffice too.

Never tried the Latex system myself, but have heard its good for scientific work. I think using some HTML WYSIWYG editor would be best for you, if you want to just focus on the content.

gnlogic
A: 

LyX

LyX is a WYSIWYM front end to LaTeX: You get the convenience of a document processor (somewhat similar to Word) with the consistency and power of LaTeX: It doesn't get in your way and can do a lot of things that professional writers need.

Note: The correct answer for you really depends on your way of thinking --- we can't decide this for you. This answer simply shows an excellent choice if you think of documentations as documents and want something similar to Word (where Word is good) that doesn't suck as Word (where Word is bad for programmers).

But many programmers think of documentation differently and hence prefer different metaphors. I myself had the same problem years ago, worked with LaTeX (as I am a mathematician), found LyX and finally settled on a Wiki/Source system that I wrote myself.

Yaakov Belch
A: 

Vim is the solution for anything that means writing plain text in the most efficient possible way. If you need formatting, then use XML, Latex or something similar (in Vim).

Vim changed my life!

alvatar
+3  A: 

LaTeX is really a very powerful language if you need to write documents.

Perhaps you can try texmaker, a cross-platform LaTeX editor:

Texmaker is a clean, highly configurable LaTeX editor with good hot key support and extensive Latex documentation. Texmaker integrates many tools needed to develop documents with LaTeX, in just one application. It has some nice features such as syntax highlighting, insertion of 370 mathematical symbols with only one click, and "structure view" of the document for easier navigation.

Oli
A: 

Simple answer: LaTeX sounds like just what you are looking for.

I use it for writing documentation myself. I will never go back to Word if I have the option.

kotlinski
A: 

I haven't got around to trying it yet, but I've always thought AsciiDoc would be good for this kind of thing.

Jon M
+1  A: 

If you want something simpler than LaTeX, you can have a look at ReStructured Text

dalloliogm
A: 

At phc, we started with latex, then moved to docbook, and have settled (permanently I hope) on Restructured Text/Sphinx.

Latex was chosen because we are academics, and latex is the tool of choice. I believe it didn't generate good enough HTML.

Docbook was chosen for power, but it was very unwieldy. It put us off writing any documentation: code had to be manually formatted, we kept forgetting the syntax, and it was difficult to read. The learning curve was also steep.

Finally, we moved to reST, using sphinx, and that was a great decision. Documentation is now very easy to write, and both PDF and HTML versions look beautiful (though the PDF could do with some customization). Its very easy to customize too.

The best bit about reST though, is that its human readable in source form. That is a wonderful advantage. I've switched to using reST for all my stuff now, especially anything over the web (except of course academic papers, where one would be foolish to use anything but latex).

Paul Biggar
A: 
JRL