Page 1 of 1
What do you use to write documentation?
Posted: Wed Oct 08, 2008 10:32 am
by Luke
I'm writing my documentation for my PHP CSV Utilities library and I've found that, while not the most difficult task I've ever faced, it isn't the easiest thing in the world to do within a word processing software like OpenOffice (which is what I've been using). I'm curious to know what those of you who write documentation use. If there's something that's not on the list and you want me to add it, just let me know.
Re: What do you use to write documentation?
Posted: Wed Oct 08, 2008 10:39 am
by onion2k
phpdoc
When I bother.
Which is rarely.

Re: What do you use to write documentation?
Posted: Wed Oct 08, 2008 10:48 am
by Luke
Oh yea not sure how I missed phpdoc. LOL.
I don't find phpdoc's results particularly useful for anything other than interface stuff though, which makes sense because that's what its for.
Re: What do you use to write documentation?
Posted: Wed Oct 08, 2008 12:12 pm
by Christopher
For non-API docs, Matthijs and I have come up with a simple HTML + jQuery Ajax solution for Skeleton that uses the Google Code Javascript library for syntax highlighting. It is really simple to style because we only use the basic H1-H5, PRE, CODE, P, etc. If you or anyone else wants to use it, it is in the repository. It would be great to work together to improve it because there really isn't anything around that is simple to use to create docs.
Re: What do you use to write documentation?
Posted: Wed Oct 08, 2008 2:37 pm
by Luke
Well that's why I've decided to write an application that does just that. I am going to call it "Dox". I started writing it last night. I actually love the way its coming along. I think you will too. Hopefully I'll have an alpha-alpha version for you to poke around in in a week or so. I'm using django to write it.
Basically I started this thread because I'd like to know the current trends in doc-writing. I'd like to make sure my application covers as much as possible.
Re: What do you use to write documentation?
Posted: Wed Oct 08, 2008 4:17 pm
by Christopher
I guess I wonder what problems you are trying to solve. We ended up with something very simple. For me the few criteria were:
1. The documentation could be easily edited by the team.
2. The page layout and styling were separate from the actual documentation content.
3. Code examples were syntax highlighted.
4. It could go on the project website or be downloaded locally, so no server required.
Re: What do you use to write documentation?
Posted: Wed Oct 08, 2008 4:37 pm
by Luke
Yes I have all of those requirements as well, but my application focuses a lot on "collaberative writing" features. It also is geared towards getting authors to simply get their thoughts down, and allows you to easily organize them after they are at least written down. I'm actually kind of excited about it. If it comes out how I plan, it will be very useful to me at the very least... possibly even useful for many.

Re: What do you use to write documentation?
Posted: Thu Oct 09, 2008 6:22 am
by wei
How about just simple plain text files using markdown text and puts these files in version control. E.g.
http://trac.symfony-project.org/browser ... ymfony.txt
Easy to read, easy to modify.
Re: What do you use to write documentation?
Posted: Thu Oct 09, 2008 1:09 pm
by Christopher
I thought of markdown, but it just adds an extra step. Someone has to build the docs rather than the change being immediate. Documentation uses so few tags (e.g. H1-H5, PRE, CODE, P) you could go from HTML to any other format as easily as from markdown. There are many, many HTML -> format x converters around.