Re: [jokosher-devel] Building a community docs site

["Jeff Ratliff" <jefrat gmail com>]

On 26/07/06, Jono Bacon <jonobacon gmail com> wrote:
> One this that became abundantly clear when the awesome 0.1
> documentation was finished, is that there is a bottleneck in terms of
> getting the docs from the docs team onto the main website - that
> bottleneck is me. The problem is that I can't restrict access to
> certain pages on the main Jokosher website for the docs team easily.
Documentation should exist to provide help and answers. We should
provide every tool that is reasonably necessary to help people use
Jokosher to it's full potential.

What we seem to be saying is:
   1) we need better documentation than most projects, including
tutorials, articles, interviews and sample projects
   2) we need to open 2-way communication with the community so they
can help each other and help us make documentation better.

I like the current jokosher.org because when you click "help" you get
current documentation. The other source of help and feedback is the
forums. I'd suggest we have the "help" button move the user
transparently to a documentation site (sounds like Wordpress is a good
idea). This site has static copies of the latest docs, and pointer
back to the forums for more "live help." That way if someone needs to
just read a manual or ask a question they need go no further. Having
comments enabled for the docs is a good idea.

This site should also connect to a Wiki, so if someone wants to help,
write a new resource, comment further, or anything else that would
benefit the community they can. I'd want people to have logins for the
Wiki, but also leave it fairly loose so people aren't afraid to try
new things. I'd also want to edit and remove things that get started
and go nowhere or encourage someone to pick them up and finish them. I
don't mind editing out crap if it means we get more good
contributions.

The third resource we need is a separate SVN repo like the art team
has. Anything that is marked up will be stored there, and the core
documentation shipped with Jokosher will be pulled from only the best
resources. Also, once we get the core stuff in DocBook, it will be
easy to write a custom stylesheet and a script to generate new copies
of the static docs for the documentation website.

Most of this is just conglomerating what other people have said. I'm
interested helping, directing, building and maintaining. I don't have
an opinion on Wikis (Trac is the first I've used extensively), but I
can get around in Wordpress and I can build a website OK.

Still haven't figured out how exaclty to handle trasnlations that
doesn't require a lot of work, but I'm working on it.

--
Jeff Ratliff (Gomer_X)