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/
Attachment:
signature.asc
Description: This is a digitally signed message part
