What do you use to write documentation?

Ye' old general discussion board. Basically, for everything that isn't covered elsewhere. Come here to shoot the breeze, shoot your mouth off, or whatever suits your fancy.
This forum is not for asking programming related questions.

Moderator: General Moderators

Post Reply

What do you use to write documentation?

Microsoft Word
1
33%
OpenOffice
0
No votes
WikiMedia
0
No votes
Another Wiki (specify which)
0
No votes
None of these (if you choose this option, post what you do use)
2
67%
 
Total votes: 3

User avatar
Luke
The Ninja Space Mod
Posts: 6424
Joined: Fri Aug 05, 2005 1:53 pm
Location: Paradise, CA

What do you use to write documentation?

Post 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.
User avatar
onion2k
Jedi Mod
Posts: 5263
Joined: Tue Dec 21, 2004 5:03 pm
Location: usrlab.com

Re: What do you use to write documentation?

Post by onion2k »

phpdoc

When I bother.

Which is rarely.

:twisted:
User avatar
Luke
The Ninja Space Mod
Posts: 6424
Joined: Fri Aug 05, 2005 1:53 pm
Location: Paradise, CA

Re: What do you use to write documentation?

Post 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.
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: What do you use to write documentation?

Post 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.
(#10850)
User avatar
Luke
The Ninja Space Mod
Posts: 6424
Joined: Fri Aug 05, 2005 1:53 pm
Location: Paradise, CA

Re: What do you use to write documentation?

Post 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.
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: What do you use to write documentation?

Post 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.
(#10850)
User avatar
Luke
The Ninja Space Mod
Posts: 6424
Joined: Fri Aug 05, 2005 1:53 pm
Location: Paradise, CA

Re: What do you use to write documentation?

Post 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. :)
wei
Forum Contributor
Posts: 140
Joined: Wed Jul 12, 2006 12:18 am

Re: What do you use to write documentation?

Post 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.
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: What do you use to write documentation?

Post 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.
(#10850)
Post Reply