11:13 a.m.
We've been trying to pull together the components to make the release
notes an effort of the Fedora community. This means developers
collaborating with writers.
This will not mean what it has in the past, with developers throwing
some bits over the wall for release notes and sometimes reading and
commenting on the drafts. When Fedora had someone paid to write
relnotes, this worked. If we can't make this work as a community effort
with resources from writers _and_ developers, we may not have any
release notes.
The first pass at an idea is on this page, scroll down to Release Notes
Process - Iteration One, April 2005:
http://fedoraproject.org/wiki/FedoraDocs/fRelNotes/RelNotesProcess
The basic idea is to break the relnotes down into modules for individual
or teams of writers to tackle. Then you would have one or more writers
dedicated to a project or subset of Linux, such as kernel, network
services, printing, UI/desktop, SELinux, etc. Then it is easier to keep
the dedicated writing resource informed throughout the development
process.
Hopefully this makes it possible for a volunteer writer to actually have
a chance to write an accurate relnotes piece in time for test or
release.
I'd like to keep this part of the discussion f-devel-l, but have Cc:'d
f-docs-l so everyone is aware it. Reply-to is set to keep the
discussion on f-devel-list.
We're also debating the merits of single source in Wiki or DocBook/XML.
Advantages of the former are the ease of collaboration and getting new
writers able to contribute sooner. The advantages of XML are too
numerous to mention, but it does suffer from a longer learning curve.
If you have any comments on that, the tool choice discussion is
happening on f-docs-l. Regardless, we'll make sure the release notes
are in the proper format on the file system for Anaconda to use.
- 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/
12:36 p.m.
On Tuesday 05 Apr 2005 17:13, Karsten Wade wrote:
We've been trying to pull together the components to make the
release
notes an effort of the Fedora community. This means developers
collaborating with writers.
This will not mean what it has in the past, with developers throwing
some bits over the wall for release notes and sometimes reading and
commenting on the drafts. When Fedora had someone paid to write
relnotes, this worked. If we can't make this work as a community effort
with resources from writers _and_ developers, we may not have any
release notes.
The first pass at an idea is on this page, scroll down to Release Notes
Process - Iteration One, April 2005:
http://fedoraproject.org/wiki/FedoraDocs/fRelNotes/RelNotesProcess
The basic idea is to break the relnotes down into modules for individual
or teams of writers to tackle. Then you would have one or more writers
dedicated to a project or subset of Linux, such as kernel, network
services, printing, UI/desktop, SELinux, etc. Then it is easier to keep
the dedicated writing resource informed throughout the development
process.
Hopefully this makes it possible for a volunteer writer to actually have
a chance to write an accurate relnotes piece in time for test or
release.
I'd like to keep this part of the discussion f-devel-l, but have Cc:'d
f-docs-l so everyone is aware it. Reply-to is set to keep the
discussion on f-devel-list.
We're also debating the merits of single source in Wiki or DocBook/XML.
Advantages of the former are the ease of collaboration and getting new
writers able to contribute sooner. The advantages of XML are too
numerous to mention, but it does suffer from a longer learning curve.
If you have any comments on that, the tool choice discussion is
happening on f-docs-l. Regardless, we'll make sure the release notes
are in the proper format on the file system for Anaconda to use.
What format would be good for inexperienced users to submit patches/docs in,
that could be parsed by either Perl or Python, which then pumps out Docbook
XML?
Either via command line or a cgi/mod_perl/mod_python page?
--
Kind Regards,
Gavin Henry.
Managing Director.
T +44 (0) 1224 279484
M +44 (0) 7930 323266
F +44 (0) 1224 742001
E ghenry(a)suretecsystems.com
Open Source. Open Solutions(tm).
http://www.suretecsystems.com/
2:32 p.m.
Uttered Gavin Henry <ghenry(a)suretecsystems.com>, spake thus:
What format would be good for inexperienced users to submit
patches/docs in,
that could be parsed by either Perl or Python, which then pumps out Docbook
XML?
Either via command line or a cgi/mod_perl/mod_python page?
There is an XML diff(1)-style program here:
http://www.logilab.org/projects/xmldiff/
It's GPL'ed; if needed I could maybe RPM it.
Cheers
3:41 p.m.
On Tue, 2005-04-05 at 14:32 -0500, Tommy Reynolds wrote:
Uttered Gavin Henry <ghenry(a)suretecsystems.com>, spake thus:
> What format would be good for inexperienced users to submit patches/docs in,
> that could be parsed by either Perl or Python, which then pumps out Docbook
> XML?
>
> Either via command line or a cgi/mod_perl/mod_python page?
There is an XML diff(1)-style program here:
http://www.logilab.org/projects/xmldiff/
It's GPL'ed; if needed I could maybe RPM it.
We've been discussing this on-and-off for a bit, because we need an XML
diffing tool for translation. The translation team uses PO files, and
the current tools they use are line dependent. Meaning, if we change
anything in the *ML, it issues a need to check for translation, even if
the content itself is no different.
One other twist in all this. The relnotes HTML is limited in the tags
it can use. Ed Bailey had a specific set of DocBook tags he used, that
did not include <*list> for example. IIRC, he would line up <para> sets
like they were bullets. This is because the HTML parser in Anaconda is
extremely primitive. There may be another HTML parser in Anaconda's
future, but right now this is our limitation.
To check out an HTML file for how Anaconda would view it, do:
python /usr/lib/anaconda/htmlbuffer.py /path/to/file.html
I asked Jeremy Katz, the Anaconda maintainer, about using plain text. I
have to do this for the FC4test2 because there is no time for me to
learn the tricks for doing it in DocBook. AIUI so far, I just don't
create an HTML version and the distro building tools will only copy over
the plain text version. Anaconda will pick that up. It mayn't be
pretty, but it'll be present. I'll work this out with release
engineering (AKA Elliott).
As I work with the Wiki on the monolithic release notes, I can say
unequivocally that it is a pain.
Perhaps if we had each section with it's own page. But then integration
into a single file for /usr/share/doc/fedora-release/ is more of a
challenge.
- 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/
5:21 p.m.
On Tue, 2005-04-05 at 13:41 -0700, Karsten Wade wrote:
As I work with the Wiki on the monolithic release notes, I can say
unequivocally that it is a pain.
Perhaps if we had each section with it's own page. But then integration
into a single file for /usr/share/doc/fedora-release/ is more of a
challenge.
My experience with them is that you pretty much have to submit and do
things the way the CMS software wants you to, or give up and find
another system (or just go mad). MoinMoin assumes heavily linked meshes
of small blocks of content...
12:10 p.m.
On Wednesday 06 April 2005 00:21, Stuart Ellis wrote:
On Tue, 2005-04-05 at 13:41 -0700, Karsten Wade wrote:
> As I work with the Wiki on the monolithic release notes, I can say
> unequivocally that it is a pain.
>
> Perhaps if we had each section with it's own page. But then integration
> into a single file for /usr/share/doc/fedora-release/ is more of a
> challenge.
My experience with them is that you pretty much have to submit and do
things the way the CMS software wants you to, or give up and find
another system (or just go mad). MoinMoin assumes heavily linked meshes
of small blocks of content...
Wich is not a problem, you can use
[[Include(subpage)]] to get single page
output.
If noone complains I will go ahead and make this change, I could also write a
MoinMoin to DocBook (or HTML) conversion.
--
http://LinuxWiki.org/RonnyBuchmann
1:21 p.m.
On Wed, 2005-04-06 at 19:10 +0200, Ronny Buchmann wrote:
On Wednesday 06 April 2005 00:21, Stuart Ellis wrote:
> On Tue, 2005-04-05 at 13:41 -0700, Karsten Wade wrote:
> > As I work with the Wiki on the monolithic release notes, I can say
> > unequivocally that it is a pain.
> >
> > Perhaps if we had each section with it's own page. But then integration
> > into a single file for /usr/share/doc/fedora-release/ is more of a
> > challenge.
>
> My experience with them is that you pretty much have to submit and do
> things the way the CMS software wants you to, or give up and find
> another system (or just go mad). MoinMoin assumes heavily linked meshes
> of small blocks of content...
Wich is not a problem, you can use [[Include(subpage)]] to get single page
output.
I see what you mean:
http://www.fedoraproject.org/wiki/FedoraDocs_2fReleaseNotes_2fCore4Test1?...
Neat.
I could also write a
MoinMoin to DocBook (or HTML) conversion.
MoinMoin > simple DocBook export would probably be a useful thing for
lots of people, not just this project, if you were interested in doing
it.
On the Fedora Wiki specifically I think that being able to pick up
material from, say, the Extras pages, as DocBook for feeding into other
documents would be useful even if we don't explicitly use the Wiki for
drafting.
2:03 p.m.
On Wednesday 06 April 2005 20:21, Stuart Ellis wrote:
On Wed, 2005-04-06 at 19:10 +0200, Ronny Buchmann wrote:
> On Wednesday 06 April 2005 00:21, Stuart Ellis wrote:
> > On Tue, 2005-04-05 at 13:41 -0700, Karsten Wade wrote:
> > > As I work with the Wiki on the monolithic release notes, I can say
> > > unequivocally that it is a pain.
> > >
> > > Perhaps if we had each section with it's own page. But then
> > > integration into a single file for /usr/share/doc/fedora-release/ is
> > > more of a challenge.
> >
> > My experience with them is that you pretty much have to submit and do
> > things the way the CMS software wants you to, or give up and find
> > another system (or just go mad). MoinMoin assumes heavily linked
> > meshes of small blocks of content...
>
> Wich is not a problem, you can use [[Include(subpage)]] to get single
> page output.
I see what you mean:
http://www.fedoraproject.org/wiki/FedoraDocs_2fReleaseNotes_2fCore4Test1?ac
tion=raw
Neat.
thanks
Reasonable PageNames are key to this.
> I could also write a
> MoinMoin to DocBook (or HTML) conversion.
MoinMoin > simple DocBook export would probably be a useful thing for
lots of people, not just this project, if you were interested in doing
it.
MoinMoin is on the way to produce xml AFAIK, but that's not in time for
FC4.
On the Fedora Wiki specifically I think that being able to pick up
material from, say, the Extras pages, as DocBook for feeding into other
documents would be useful even if we don't explicitly use the Wiki for
drafting.
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?
--
http://LinuxWiki.org/RonnyBuchmann
10:32 p.m.
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/
12:28 p.m.
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
1:21 p.m.
Just a couple observations...
On Thu, 2005-04-07 at 19:28 +0200, Ronny Buchmann wrote:
[...snip...]
> 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).
Which is why the Emacs psgml mode is helpful. There are plenty of other
Emacs packages, that's just what I use. Only a few keystrokes to
remember, and you don't have to remember *any* tags since you can get a
list at any time, which is true for many of the other packages. I've
found the tagging to be easy enough that I use DocBook for non-FDP stuff
(like real, paying work!) nowadays.
[...snip...]
> 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.
Correct, but that's not what Karsten said. He said that the three
factors of (1) content, (2) tools, and (3) writing processes {will,}
make our docs better. Many of the tutorials you can find on the Web at
large are poorly marked, narrated, and organized. It makes following
them difficult for people who speak the same language as the writer,
much less for non-native speakers. Our content, tools, and processes
are designed to make reading, understanding, contribution, editing, and
translation as easy as possible.
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
5:14 p.m.
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/
2:58 p.m.
On Tuesday 05 April 2005 22:41, Karsten Wade wrote:
On Tue, 2005-04-05 at 14:32 -0500, Tommy Reynolds wrote:
> Uttered Gavin Henry <ghenry(a)suretecsystems.com>, spake thus:
> > What format would be good for inexperienced users to submit
> > patches/docs in, that could be parsed by either Perl or Python, which
> > then pumps out Docbook XML?
> >
> > Either via command line or a cgi/mod_perl/mod_python page?
>
> There is an XML diff(1)-style program here:
>
> http://www.logilab.org/projects/xmldiff/
>
> It's GPL'ed; if needed I could maybe RPM it.
We've been discussing this on-and-off for a bit, because we need an XML
diffing tool for translation. The translation team uses PO files, and
the current tools they use are line dependent. Meaning, if we change
anything in the *ML, it issues a need to check for translation, even if
the content itself is no different.
Translation of docs with po files is a pain in
the ass (I speak from
experience with anaconda-help).
MoinMoin uses character based diff, which is much more helpful. (Editors
should use the Bookmark feature in RecentChanges to have a diff from last
visited version of pages).
One other twist in all this. The relnotes HTML is limited in the
tags
it can use. Ed Bailey had a specific set of DocBook tags he used, that
did not include <*list> for example. IIRC, he would line up <para> sets
like they were bullets. This is because the HTML parser in Anaconda is
extremely primitive. There may be another HTML parser in Anaconda's
future, but right now this is our limitation.
So DocBook wouldn't help at all?
Putting a bit of work into htmlbuffer might be better usage of resources.
Or will anaconda use docbook(xml) directly?
As I work with the Wiki on the monolithic release notes, I can say
unequivocally that it is a pain.
Perhaps if we had each section with it's own page. But then integration
into a single file for /usr/share/doc/fedora-release/ is more of a
challenge.
now have a look at
http://fedoraproject.org/wiki/FedoraDocs_2fReleaseNotes_2fCore4Test1
--
http://LinuxWiki.org/RonnyBuchmann
6950
days inactive
6953
days old
12 comments
6 participants
participants (6)
-
Gavin Henry -
Karsten Wade -
Paul W. Frields -
Ronny Buchmann -
Stuart Ellis -
Tommy Reynolds