[RFC] making release notes a community effort

Thu Apr 7 17:28:41 UTC 2005

On Thursday 07 April 2005 05:32, Karsten Wade wrote:
> On Wed, 2005-04-06 at 21:03 +0200, Ronny Buchmann wrote:
> > It would be really helpful to have a recent MoinMoin installation on
> > fedoraproject.org, this would reduce some work needed (it produces
> > [almost] valid html) and is IMHO much more easy to use. (see
> > Linuxwiki.org for example)
> >
> > Who maintains fedoraproject.org?
>
> Seth Vidal, but don't bug him about it.  The problem is the data
> migration between the versions, making it a not-pain-free upgrade path.
Actually it's about running nine python scripts on the data and adjusting the 
config, all in all it takes about half an hour (I've done it for a corporate 
and a private wiki)

> My first challenge is with version control.  Using CVS on the command
> line, I can get all kinds of useful information to parse with CLI tools.
> This helps when maintaining a document set.  For example, I couldn't
> tell if you and I stepped on each other today in the Wiki.  I think I
It's actually a bit better with MoinMoin, because auf the automatic page lock 
(ok, this doesn't help with reorganizing)
you can't edit an old version, as with cvs

> now understand a little better, having just gone through reverting a
> change.  I find using a GUI for version control to be like using a GUI
> for file management.  Except the Wiki doesn't have the single nice thing
> about GUI file management, drag-n-drop.
MoinMoin 1.3 has at least rename

> The looser methods of accountability that a Wiki provides highlights the
> reason for having a process and ownership of the components.  We really
> can't have just anyone come in and edit the release notes.  The
> capability of backing out a change does not make up for a lack of
> control over the content.  Hopefully someone notices in time the
> prankster that changes the command to "rm -rf /" ...
(My) experience shows that the lack of single control is working quite well.

> My biggest problem with using the Wiki was demonstrated today when you
> broke the relnotes into a bunch of smaller pages.  I had been thinking
> this would work out OK , but now I see the problems:
>
> 1. I have to create a watch for all those pages.  To do that, first I
> have to know they exist.  How does one even find out about all the pages
> easily?  I only know they exist because I was going through the
> RecentChanges trying to figure out why you redirected from
> FedoraDocs/RelNotes/RelNotesProcess to
> FedoraDocs/ReleaseNotes/EditingProcess.
reorganizing is not a usual task (you don't remove and add files in cvs 
without a good reason, too)

you can watch "FedoraDocs.*"

> Compare this to how easy it is to watch check-ins to a module in an SCM
> such as CVS or SVN, with unified diffs and other useful contextual
> information.
>
> Perhaps it's this easy in the Wiki.  It hasn't been so far for me.  It
> seems as if it will get harder as the structure grows and changes.
One Wiki per "module" (i.e. docs, extras) would be working better

> 2. The pages are in a namespace that reflects a) personal taste and b)
> needs to be manually updated every time we reorganize the release notes.
>
> As for a), I gather that what you did today is smarter Wiki naming.
> That's cool to know how to do, except I don't want to have to name my
> documentation because of Wiki limitations.  Probably where my weird
> naming scheme came from the in the first place!  Which leads to ...
You can have any arbitrary name for pages, but do you choose any arbitrary 
name for files?
There is no wiki limitation here.

> About b), I have been trying to figure out a better structure for the
> namespace of the FDP pages.  fedoraproject.org --> FedoraDocs is
> redundant, and the layout of the rest of the site tends to follow the
> idea of dropping the Fedora.  I _think_ I agree with this.
Yes and subpages are not very common in Wikis and should be used with care, 
pages at the top level are much more usual.

> Therefore, DocsProject/Foo and Docs/Foo are the two ways I was thinking
> we should go.  Now, unfortunately, we have a number of pages to
> deprecate and redirect to a new set of pages.
Or simply delete (if links were not used externally)

> This happens every time we reorganize a doc.  I have received several
> good ideas to tryout for test3 relnotes, which would change the WikiName
> of more than one of the pages.  More pages to manually handle.
Ok the PageName in MoinMoin is shown in really big letters, but this could be 
changed easily

> DocBook does all this kind of stuff much more smoothly, IMHO.  One or
> more directories full of real files that are built a parent document.
> It also is more powerful, letting you have the full range of CLI tools
> to manipulate doc sets.  This may not matter when you are dealing with a
> single how-to, but for a bunch of them, it makes a difference.
>
> 3. Wiki accountability is harder to maintain.  For example, you assumed
> the relnotes process doc was about editing the relnotes and renamed the
> page, which in WikiLand deprecates and redirects.
You mean I should have read the page before ;)
This can be changed to any other better name of course.

> In fact, how we manage the editing of the relnotes is just a part of the
> process doc.  I suppose I could go back and create -another- page that
> is the parent page about relnotes, and etc.  Or revert that one.  In the
> meantime, where is the process documentation?  And under which of the
> three competing namespaces should I place this new process doc?
I would argue for something like ReleaseNotesProcess (or maybe 
FedoraDocs/ReleaseNotesProcess if we keep the top level page)
It's just a matter of taste.

> The nature of the Wiki is to make one want to get in and fix stuff.
> Unfortunately, following this philosophy can lead to redoing a lot of
> work that was not authorized by the project.  Is that anti-collaborative
> of me?  No.
This could be controled with ACLs. (We already have EditGroup, which are not 
many people, but a DocsProjectGroup is possible, too)
I would not make the restrictions too high.

> We discuss on list the changes we want to make to things, and have a
> process to vet those changes.  It's collaborative, it just has more
> order to it.
I think people like working with wikis or they don't. I've seen several 
discussion like this and changing opinions are rare.

> 4. Wiki editing sucks.  I used a real text editor today.  This would
> obviously be easier with smaller pages, but that has its own set of
> problems, as I've discussed.
Yep, this is a real problem

> To keep from having to keep clicking "Preview" while I was working in
> Emacs, I put in a manual note in the relnotes today saying not to edit
> while I worked in it offline.
no difference to cvs

> How does a Wiki handle collisions and merges?  Can it be as smart as a
> full SCM system?  Heck, can we get the changelog to accept more than a
> few dozen characters?  Sometimes I have multiple paragraphs to say about
> a check-in.
depends on the wiki engine

> With DocBook, I can move sections around at will and rework naming
> schemes with search and replace in Emacs or with sed.  It is very
> friendly to messing with a set of documents.  I've never found a Wiki to
> be this way.
accessing the page source with a SCM can be done

> I have serious reservations about having the Wiki be canonical for the
> release notes.  It seems to be *much* easier to author in DocBook and
> paste a plain text output into a Wiki page each test and release.
DocBook is not bad, but typing tags is a pain (learning hundreds of keystrokes 
or clicking isn't better).

> Because of the differences in the way a Wiki must have names and the way
> we want to put together DocBook <article>s, I'm not sure about the
> future of Wiki2DocBook conversion.
There is no naming problem, really (you don't need CamelCase, any ["arbitrary 
link whatsoever"] works).

> This project is regularly criticized for not taking advantage of the
> ease of publishing with Wikis.  I am willing to review that policy, but
> we have to keep in mind the fact that quality rules over quantity.
> There are plenty of bad and just-good-enough Linux docs out there.  Ours
> are and will be better.  This is because of the quality of our content,
> tools, and writing processes.
I don't think the quality of the content is related to the tools.

-- 
http://LinuxWiki.org/RonnyBuchmann