OSS Project Documentation

[Jeff Garland]

Darrin Chandler wrote:
> On Wed, Apr 11, 2007 at 09:41:49AM -0700, DX wrote:
>> Does anybody know any good php based documentation software. I just
>> recently started on a new project and one of the requirements is that
>> everything gets documented properly, but even more important, they want
>> documentation not only to be inside the code itself but management also
>> wants to be able to access the documentation.  
>>
>> My thoughts on this requirement is that I'm going to have to write two
>> documentation sets, one for the code itself and one for others to see.
>> The one I'm more concerned about is the one for others to see. I was
>> thinking of having a type of blog where I can enter which part of the
>> project is referring to and what does it do, as well as how to use it. I
>> don't think a blog will be good enough so I was wondering if there are
>> any php tools for documenting software that would help me out. I'm
>> looking for a web based solution so anyone can access it.
> 
> Sounds like you want a wiki. MediaWiki is popular, but there are several
> others that are also popular and well regarded. Many people use wikis
> for internal company documentation. Alan Dayley was just talking about
> using one at his work.
> 
> I'm sure others here can give you good specific suggestions.
> 

What I've done in the past is use Doxygen in combination with a Wiki.  Doxygen 
can take comments out of code to generate web pages with 'reference style 
detailed docs'.  Doxygen can also generate more tutorial and 'user guide' like 
documentation, but I prefer to use a Wiki for that.  Eventually I had a couple 
  perl scripts that could run the doxygen over the latest baseline, spider 
down the latest wiki pages, reformat the wiki pages into a nicer format, and 
convert all the links between the wiki and reference materials into a set 
'local referenced' web pages -- this was so this set of 'static web docs' 
could be installed on a hard drive or on any web server by just copying files.

Unfortunately, all I can share is the idea...corporations own the details...

As for Wiki's, there's a ton of them -- I mostly use UseMod (perl based) 
because I've had to hack the internals so I know it pretty well and I hate 
installing databases for small wikis. At one point 5 years back WikiPedia used 
UseMod. MediaWiki is the 'big daddy' since that's what Wikipedia uses -- 
probably pretty hard to set up. If you're doing php do a search on PHP wiki 
and you'll find one.

Jeff