Re: Wiki user guide

[karderio <karderio gmail com>]

Hi :o)

On Wed, 2006-07-05 at 09:08 +0100, Joachim Noreiko wrote:
> (ccing the docs list to include everybody
> The background: karderio and I are discussing the
> cleaning up of the User Guide pages on the wiki)
> 
> --- karderio <karderio gmail com> wrote:
> 
> > Hi :)
> > 
> > I got your message on the user guide wiki page, I
> > agree that this
> > doesn't seem to have been successful.
> > 
> > I'm going to finish tagging the pages anyhow, as it
> > is no more work to
> > finish what I started as to go and remove the tags I
> > have already
> > added ;) I have added a note to the insert saying
> > that these pages are
> > outdated.
> > 
> > As I mentioned on the doc-list, I think it would be
> > a good idea to put
> > the docs as they are on to the wiki, that way people
> > can correct /
> > update them. It would be even easier for the
> > contributor to do this than
> > to file a bug report. Before each release, we would
> > just do a diff to
> > see what people have changed and integrate it into
> > the official docs, or
> > discard it if it is not relevant.
> 
> It's a lot of work to get our current docs onto the
> wiki, and then every time we make changes in CVS we'd
> have to update the wiki too.
> Using bugzilla allows someone to just say "this bit of
> the guide is wrong" without needing to supply the
> correction.

Well, the way I envision it, it shouldn't be much work at all (except
perhaps for me, at the beginning) : I thought I would write a Python
script (oh beautiful Python !) that could pull the docs from CVS to the
wiki.

To start the ball rolling, we make a file with a list of documentation
with cvs addresses, this will be the only thing needed to be maintained,
and only when we add or move docs. We then run the script and hey
presto, it populates the wiki with our current documentation.

The script would also be able to give a list of differences between the
docs in cvs and the ones on the wiki, to see what has been changed.

Before each release, we run the script to get the diffs and integrate
any interesting ones into the documentation. After each release we'd
just run the script and nuke everything that was on the wiki, replacing
it with our shiny new docs for further community corrections.

I already have scripts for moinmoin that can replace arbitrary strings
in a list of pages, and transfer a list of pages from one wiki to the
other. I wrote these for the ubuntu wiki, but they have the base for the
work to write a documentation managing script, so writing the script
shouldn't be too hard.

> What I think would be most useful for the wiki would
> be to list the UG's table of contents only, and mark
> on it:
> * sections that need updating
> * new sections we know need to be written
>
> These can then be worked on new pages by people who
> don't want to use DocBook and CVS.
> So we'd be updating and extending the guide on the
> wiki, but without all the extra work of keeping a
> perfect copy there.
> 
> It would also give us an overview of the guide's
> current structure, and we can discuss ideas to
> rearrange it.
> What do you think?

Well, this seems somewhat similar to what we had already : an index that
writers would add the content to, except that currently we don't have
the actual index, but a new index that represents how things should be
after reorganisation (at least that is the theory, I suppose).

Without having the actual content there, it would not be as easy to make
a modification to the existing docs, such as a reformulation, spelling
correction, add/modify a step etc... Having the content could also keep
modification in context, with the former system some of the comments
seemed to have been copy/pasted from a welsh cook book :) (not to
criticise, a lot of it I found very useful)

One major problem I found with the current system when using the wiki
content to put in the nautilus part of the user guide, is that most of
the content was duplicate. Having the content here would avoid this.

Another problem with the wiki, whatever system we use, was that the
style of what people were writing was totally inappropriate for use in
docs. Perhaps we should insist more on the style guide, or even resume
it for the wiki.

Well, that's what I think at the moment, don't know if any of that is
anything other than rubbish :)


Love, Karderio