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
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
