Re: Docs.

On Mon, 27 Nov 2006, Lance Levsen wrote:
>
> I'll look at figuring out the PDF issues, I've done that before from 
> Docbook, so I should be able to get it working. It might change the 
> Makefile though (no automake! :( )

Yeah--that's fine.  And adjusting some of the markup to make it work 
better is fine, too.  When you convert to a PDF, it'll be pretty obvious 
which sections don't really work right.


> Will, how do you want me to patch the docs? svn to SouceForge or patches 
> to you?

My gut reaction is that I want to do an editing pass over all changes to 
the manual because it's the central documentation source for PyBlosxom.

But...  given that I've been craptastic at getting things done, it's a 
terrible idea to stick me in the middle of any process.  So if you have a 
sourceforge id, I'll add you to the project and you can do the checkins 
directly.  I'll just watch the checkins list and if there are problems, 
I'll talk to you about them.


> Also, I changed the author to Pyblosxom Development Team from Will, is 
> that cool with you?  I didn't change the copyright.

Well, given that I've put a lot of work into that document, I think I'd 
rather have a list of authors rather than a vague attribution to 
"PyBlosxom Development Team".  A couple of years ago I would have said 
change it, no biggie.  These days I think it's better to make it clear who 
worked on what.  It's better for the end user because they have a clearer 
idea of who to complain to.  It's better for the person doing the work 
because having their name on things shows the work they've put in.  It's 
better for the project because it's clearer who was responsible for what.

I'd be interested to hear other peoples' points of view on the matter if 
there are other points of view.  This doesn't just affect documentation, 
it affects any work done on the project.



> At the moment, the only changes I've made are up to the install/trouble 
> shooting pages. I have to spend time going all administrator to get the 
> mod_python/Twisted/WSGI stuff written. Any other application server 
> stuff that I should look at? (Zope, TuboGears, CherryPy)

I think we definitely want WSGI documentation in there and along with that 
FastCGI.  Beyond that I think mod_python, Twisted, SCGI, ...  are kind of 
fringe.  That's based on watching Pylons and the Python web application 
space.

I don't want to get into the situation where we have lots of installation 
methods and no one who really knows them well enough to update them over 
the next few years.  I was tossing around taking those pieces out of the 
manual and instead hosting them somewhere else on the site in a more 
"use-case scenario" article section.

This is one of those times where I wish we had a wiki running for this 
kind of details documentation.

/will

-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV