[RFC] making release notes a community effort

[Karsten Wade]

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.

Ronny, I really appreciate your effort and ideas.  I don't want to
discourage your enthusiasm.  I'm going to use your Wiki edits from today
as an example of the problems I have with using a Wiki for the release
notes, really for any large-scale documentation effort.  Don't take this
as a dismissal of you or negative criticism of the quality of your work.
This is just constructive criticism of an otherwise great tool.

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
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.

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 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.

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.

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 ...

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.

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.

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.

As the relnotes grow and are made more modular, the maintenance
nightmare increases.

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.  

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?

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.

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.

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.

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.

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.

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. 

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.

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.

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.

- Karsten
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
                       Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20050406/3d00c557/attachment.sig>