Re: pyblosxom 1.2 timeline

On Fri, 4 Mar 2005, Steven Armstrong wrote:
>>
>> And documentation needs work.  I have some stuff half-written that 
>> needs to be finished and go into the "manual".  I also need to fix the 
>> manual so that it's versioned alongside PyBlosxom (i.e. we have a 1.1 
>> manual that's separate from the 1.2 manual...).
>
> How are you writing the docs? Maybe it would be clever, if not so 
> already, if we had some generic doc-format here (Docbook, GuideXML [1], 
> LaTeX, whatever). So if someone wants to contribute some documentation 
> you get it in a specified format instead of mail, or doc (yuck) or 
> whatever (== less work for you to intergrate).
>
> [1] http://www.gentoo.org/doc/en/xml-guide.xml (this is really nice)

I have to do some work work right now htat I need to finish up before I 
leave tonight, so I'm just going to respond to the documentation part 
right now.

We've had some interesting discussions over the last couple of years in 
regards to how we should do documentation.  Previously most people were 
fans of putting documentation in the wiki and then there were minor pieces 
(install guide, readme...) that were in plain text in the CVS repository.

I still dislike the wiki method mostly because we didn't have an active 
editor so it's anyone's guess as to how accurate the wiki data was.  The 
documentation I've been doing is in the form of html and it gets sourced 
by my staticfile plugin for the web-site.

I suggested using docbook or reST a while back, but no one was really 
interested and I wasn't motivated enough to actually write the 
documentation.  Maybe we should re-consider that decision in light of 
other people helping out.

I _really_ like the idea of allowing other people to comment on the 
individual chapters of the manual--that's incredibly useful since it 
allows regular users to add content to the manual and their own solutions 
to various problems.  It's interesting to note that no one has used this 
feature of the web-site yet so it's possible that it's only interesting in 
theory but not in practice.

I'll look into converting what I've got to docbook (I've written a very 
little amount of docbook in my life) and see how that might work.

/will


-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click