Jargon Buster wikification

[Paul W. Frields]

I'm taking this discussion to the fedora-docs-list so that others can
offer their input.  We should try and keep these discussions there so
the community can get informed and involved.

On Sat, 2006-11-18 at 23:00 +0300, John Babich wrote:
> I agree that needless movement between DocBook XML and the wiki can be
> a waste of time, and almost always should be avoided. Editing in the
> wiki can be a crutch and prevent people like me from learning Emacs in
> greater depth, which is one of my reasons for wanting to be involved
> in the project in the first place.

I like the idea of more contributions to the glossary.  It's a worthy
goal.  I just wish that, at the same time as we get more contributions,
we were also encouraging people to submit the changes in a more
automatically trackable way.  That way is Bugzilla.  (I'm reminded that
random people can't contribute to our wiki -- they have to go through a
series of steps (you've done them, of course) including the CLA.)

Wiki notifications are a fine way for anyone currently using the wiki to
pick up "what needs to be done."  But what about John Newuser, who just
joined?  He starts at square one, and even if he has CVS and DocBook
skills, and is well-informed enough to turn on all his notifications
immediately, he will have no idea what entries need to be moved.  He
can't get backdated notifications.

Bugzilla is a queue of problems that any motivated contributor can
consult for a "to-do" list.  John Newuser can look at the list, pick a
problem, and get down to business.  Bug and task tracking tools are the
ideal way to capture this work, and produce other useful information
like how long it's taking to get them closed or handled.  The wiki
satisfies none of those needs, unfortunately.

Again, I'm not blasting use of the wiki -- but it's very clear to me
that it's not a sustainable and valuable tool in the way that SCM and
Bugzilla clearly are.  It's merely good for collecting raw material
quickly.

[...snip...]
> So I agree that DocBook XML is the almost always best way to go.
> Karsten, you shared some great ideas on improving the online editing
> through some Python programming to make more of a workflow among the
> writers / editors / translators. This can then be captured as valid
> DocBook XML through an easy-to-use feature.

Again, there's a reason everyone uses DocBook! :-)

> However, the Glossary may be the exception to the "Always write in
> Docbook XML" rule. Of all the documents, the [Fedora] Glossary page
> can be very useful if used on the wiki in its full form. That's one
> reason I suggested it.

However, it can't be useful from that location for packaging or
alternate publishing methods such as HTML, PDF, and/or RPM packaging.

> I see it as a place where we, the Docs Team, as well as all the other
> Wiki users, can add technical terms as needed to make online entries
> more accessible to our entire range of readers.  For instance, I
> didn't have a clue what SCIM is - until I saw it in the glossary.

Again, a good Bugzilla template would also work, and users would only
need to fill in the name of the term.  A writer and/or editor could
write the definition from scratch if the contributor couldn't, or didn't
want to.

> If we keep a copy of the glossary on the wiki, which can grow
> organically as people add new terms, then I believe it becomes a more
> useful tool. When it reaches a certain level of maturity, then a
> snapshot can be captured of the wiki glossary and converted to a more
> permanent form. (That's where the "convert to DocBook XML" button
> would come in handy.) Even then, it will keep evolving on the wiki.
> 
> Correct me if I'm wrong, but the Glossary seems pretty modular by
> nature and lends itself to "chunky" updates. Does that make it easier
> or harder to convert?

I was hoping "easier," at first, but the more I think about it, the more
I think you're making my job (as editor) very difficult.  The wiki can't
capture cross references well, for example.  Every time we snapshot the
page for a DocBook conversion, we will have to reconvert all those cross
references, of which a good glossary will be chock full.  There are
probably other high-visibility tags in there that are going to be a real
PITA to convert.

> The Glossary can also serve as a convenient place to refer people from
> other documents such as tutorials. For example, "See SCIM in the
> Glossary for more detail".

Yes, but that's no different than an online HTML publication. :-) 

Again, I think there are good arguments on both sides, and I am happy to
simply try and keep up with the wiki changes at this point, integrating
them into the canonical CVS copy.  I think the next 18 months will see a
big change if enough people start getting involved[1] in learning about
the CMS and how to make it do what Fedora needs for documentation
efforts.

= = =
[1] To that end, I installed Zope and Plone and have been running some
tutorials to start getting my brain wrapped around how this stuff works.
I would recommend others do likewise; the installation and running the
tutorial are quite simple, and I'm happy to write a short checklist of
how to accomplish these steps if anyone needs it.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
       Fedora Project Board: http://fedoraproject.org/wiki/Board
    Fedora Docs Project:  http://fedoraproject.org/wiki/DocsProject
-------------- 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/20061118/fc0f98cb/attachment.sig>