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 <[EMAIL PROTECTED]> 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 _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
