Documentation Software

[Neil]

This is probably a bad place to ask since rom hackers as a general rule seem to be the most disorganized people in the world, but does anyone here have any documentation creation/management software they swear on? I've been tasked at work with documenting the projects that I've been working on the past three years (department is expanding!) and I'm trying to find something that's got robust support for revision control, can handle various forms of data (text or xml metadata, images, etc) and has the ability to compile the data into something presentable with a table of contents, etc. I thought about using a wiki... but as a general rule wikis seem to be no better than writing something in word, printing it out, and tossing it up in the air. I.e. you tend to end up with well written pages with no sense of context, flow, or organization.

Suggestions?

[PhOeNiX]

I don't know if you are talking about source code documentation or project documentation. For documenting code, you would use an automated doc generator like doxygen or javadoc if you are programming in java.For projects documentation you should use UML instead, describing your applications architectures and then write a doc explaining your design strategies and commenting the UML diagrams.
.

[Neil]

I don't know if you are talking about source code documentation or project documentation.

That and more. I need to have a centralized location to contain project, source code, and file documentation (the latter for spatial dataset metadata to be specific). Basically I need to create a training manual and reference database in one fell swoop and hopefully have it in some way that allows for easy reading and easy maintaining as it will need to be updated regularly. I don't even know if such a thing exists...

[PhOeNiX]

Mmm, as i understand, you need something similar to github or google code, but on your local machine . If your code is fre,e you should be confortable uploading your programs on github and then use its features to achieve your goals. For closed source projects, mm you should use some other tool like that wich can be downloaded and executed on your local machine.

[Neil]

This looks shiny and hasn't actually been released yet, but looks like it might be along the lines of what I'm looking for : http://www.exia.net/ExiaProcess/ExiaProcess.aspx

Maybe I just bite the bullet and use sharepoint, dump to that bastardized format microsoft calls office xml, and compile into documentation manually.

[Kiyoshi Aman]

If you use a VCS (git, hg, etc.), there's plenty of open-source software for making the repositories viewable via the browser (cgit for git, hgweb for hg, cvsview for cvs/svn, etc.). I would personally also use a wiki & bug tracker in combination with the repo viewer.

I would not, however, recommend project managers like Trac or Redmine. Personal experience with Redmine's been that it DoSes itself on a fairly regular basis unless you hand it unreasonably generous resources, and Trac just plain blows.

(Credentials: I'm an Atheme.org developer, and I manage (along with others) Atheme.org's JIRA and Confluence instances, as well as the repos.)

[Neil]

The source documentation I'm not worried about. There are plenty of free and other programs out there for that... It's the project documentation I'm mostly worried about. I do not want to work in word. I would ideally like something with real revision control, something with the ability to link everything together, etc.

[Klarth]

Do you have a project manager (assuming you're not it)?  If so, ask if there's any in-house project management software and if everybody necessary can access it.  You could (*chuckle*) use Word + MS Project + Sharepoint.  There's other project management software suites as well, some free.  If you're cutting that solution out as well as wiki...I'd probably make a quick and dirty script that links your content together (into a .pdf, .chm, .html, whatever) that is ran upon a project commit to SVN/git.  There's probably something available that does this already (other than wiki), but I'm unaware of it.

And is this programming project information?  Historical data, etc?  Those things are useful.  A program I use in the past for note taking is called Scribe if you're working on a book and need to keep your facts referenced.  Nowadays I'm lazy and use OneNote. 

[Kiyoshi Aman]

The source documentation I'm not worried about. There are plenty of free and other programs out there for that... It's the project documentation I'm mostly worried about. I do not want to work in word. I would ideally like something with real revision control, something with the ability to link everything together, etc.

Right, in which case you want a wiki. If you don't mind using externally-hosted software, I would highly recommend Wikidot, as it's extremely customizable (almost as if you were hosting it yourself, really), even on free wikis. I don't know if you can white-label it, however. Failing that, Wikipædia has a list of wiki software you could peruse.

[meunierd]

The source documentation I'm not worried about. There are plenty of free and other programs out there for that... It's the project documentation I'm mostly worried about. I do not want to work in word. I would ideally like something with real revision control, something with the ability to link everything together, etc.

Sounds to me like you want a wiki, and there's lots of options there. Some integrated with project-hosting solutions, some not. Trac/DrProject tries to be a catch all solution. If it doesn't fit the bill for you, I'd be curious as to why since my uni in part develops DrProject (which is itself a trac fork).

EDIT: http://basieproject.org/ Basie seems to have grown out of the Dr Project (project) as well.