[RFC] making release notes a community effort

[Karsten Wade]

On Thu, 2005-04-07 at 19:28 +0200, Ronny Buchmann wrote:
> On Thursday 07 April 2005 05:32, Karsten Wade wrote:

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

This is probably a personal thing.  I feel trapped with the Wiki
versioning, I have to check each page manually, etc.  With CVS, I can
get data on an entire tree and parse it with standard CLI tools.

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

Except where you renamed a document that you hadn't read thoroughly,
right? ;-D

Okay, okay, I know this can happen in CVS.  We could have ACLs to define
who gets to edit what, etc.  Then we would be duplicating what we have
in CVS, and have to do dual maintenance.

Were we to abandon DocBook for technical documentation in favor of a
Wiki, then it would make sense to build dual authentication
infrastructure before a switchover.  But we're not. :)

> reorganizing is not a usual task (you don't remove and add files in cvs 
> without a good reason, too)

There are two types of reorganization, of content and of files holding
content.

In DocBook, I don't have to break out <chapter>s and <section>s into
individual files unless I want to.  Then renaming them is easy in CVS.
The names of the files has zero impact on the names within the resulting
documentation.  Therefore, I can restructure the files at-will and not
having to change a single external URL reference.

Where DocBook _would_ affect external URL references is in the internal
structure of the content.  Then all I have to do is move sections of
text around in some files.  If I'm following a standard ID convention, I
may not even have to change that many references.

How this affects the release notes is that whenever we restructure the
relnotes for a new test or release, the resulting Wiki restructuring
makes readers learn a whole new way to read the relnotes.  It also makes
a whole new structure for writers to learn.  Any deep-linking would have
to change.

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

Sorry, I thought you had devised a new naming convention because it was
better for the Wiki.

Again, changes in the structure of content in plain text or DocBook
don't require the files to be renamed, necessarily.

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

Why?  Is this a limitation in Wikis?  It's sure a nice way to sort and
store information.

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

If.

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

Don't understand what you mean here.

The reorganization would require the addition or subtraction of words
within the title of a particular section.  Which would change the
WikiName to SomeOtherWikiName.

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

Right.  But that's not the point.

Without setting up a duplicate authentication system that locks down the
Wiki in a way its not meant to be used, anyone such as yourself can come
along and mess with the documentation.  Nice collaboration, but it
lowers the reliability for writers and readers.

I want to put docs in Wiki that _should_ be put there.  They should
follow the philosophy of a Wiki, that is, a larger group writing effort.
So far, none of our docs fits that model.  FedoraNews.org and others are
doing great work in this space, I see no need to compete and repeat
effort.

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

DocsProject/RelNotesProcess also would work.

Regardless, it's something we decide first.

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

I like working with Wikis, where they are appropriate.  I worked with
them for the relnotes, and don't feel they are appropriate.  If I
thought developers would actually go in and put in content, that would
greatly affect my opinion here.  But they most likely will not.
Therefore, I want a solution that best supports the writers and editors
who will be doing the work.  I don't think that of the Wiki,
_in_this_case_.

I'm interested in Wiki doc work that a) doesn't unnecessarily repeat
what others are doing, and b) is appropriate for a Wiki.

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

True.

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

Yeah, this also was a complaint about this implementation, not against
Wikis in general. :)

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

OK

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

This is why we recommend Emacs + PSGML(x).  When nXML is more mature,
that will great.  Mark Johnson's psgmlx adds lots of nice features such
as a right-click context menu that lists all the tags that are available
in that particular spot in the markup.

It is a bigger learning curve.  We are doing what we can to make it
easier.

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

Paul explained this pretty well.

It goes back to why Red Hat has the quality of guides that it has.  For
the docs of the same quality or better as Fedora Core itself, we need
processes, tools, and good content. 

- 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: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20050408/9d34ed51/attachment.bin