On Fri, 2006-11-17 at 00:18 +0300, John Babich wrote: > Karsten, Paul and Fellow Team Members: John, this is a good write-up that reflects mostly-accurately the grown-to situation we are in. That is, we have organically grown into "what works" as much as we have planned it carefully. Feel free to update the DocsProject pages in the Wiki to reflect this approach, where it fails to make that clear. Because of the organic growth, we haven't always gone back to clean up the various leftover processes and half-completed ideas. Still, seeing this clarity from you gives me hope that it can be equally clear for others. :) Just a few additions/corrections/observations: > Now more than ever, the Fedora Project has captured the public's > attention. Now is the time to improve the "public face" of Fedora. Agreed. In fact, I think there is some sentiment that Fedora can begin to do more self-promotion. To be honest, I think the Fedora Project has been afraid of users who are new to Linux. That is, the fear is not amongst the ground folks who solve problems daily on fedora-list, #fedora, fedoraforum.org, etc. I mean the project leadership and majority of technical achievers. I've long maintained that Fedora is both what we want it to be and what it becomes by itself. This is one reason that the FDP focuses on users of all levels, even where the overall project does not advertise itself as "for the beginner". Honestly, I don't think the technical situation is going to change. Fedora is always going to have more leading-edge technology and associated rough user experience. That just makes our jobs here that much more important. While the solution to document something instead of make it work better without documentation is not my favorite solution, I want to get to a point where highly technical contributors in Fedora are using good documentation as a way to mitigate the challenges of being so leading-edge. > Forgive me in advance for the length of this correspondence. I hope > you find it worthwhile. Personally, it makes me proud of our work to have a newer someone feed the situation back so accurately. > THE WAY FORWARD > > Here are some ideas I find encouraging (I take full responsibility for > any misinterpretations). > These are also very much open for discussion and debate. > > 1. MoinMoin Wiki - to jointly revise documents > > Currently, we are taking this approach with the "Software Management > Guide". Once we're happy with the results, we can then turn guides > like this into more permanent forms like DocBook XML. I am looking > into ways to use Gedit and the new Plugins feature to speed up the > process. The "Tag Lines" plugin looks very promising. This keeps the > barrier to entry very low. > > ADVANTAGE: Ease-of-use, low barrier to entry. Eclipse may also have a plug-in for working offline. If it doesn't, we should get someone to write one. The purpose is to increase the documentation we get from Fedora developers. There are also a number of ways that content comes into FDP that you didn't cover here. These are discussed here: http://fedoraproject.org/wiki/DocsProject/ReleaseNotes/Process#submitting Note number 4. There are also new ways that RHEL developers can make commits to CVS and have them update bugzilla reports, etc. That is a process and toolchain we need to learn more about and find out how to make it fit into the release notes process. The idea is that we can take in all manner of content suggestions, and some goes to release notes, others to installation guide, admin guide, desktop guide, etc. > 2. Plone Content Management System (CMS) - for a more polished look > > We can use the Plone application for static pages and a more polished > look. Of course, we need to decide what exactly is "static" versus > "dynamic". I propose that the "index.html" or equivalent be static, > with dynamic updating going on in Drafts. Once a document is > finalized, then we can make it "static" in Plone and jointly edit the > new version in MoinMoin. > > ADVANTAGE: Polished presentation and possible improvement in maintenance. Guaranteed improvements in maintenance. :) Our current publishing situation for anything that is not the Wiki is quite daunting. Plone as a CMS provides us with workflow. This means a writer can submit, and editor can edit (push back for change acceptance, forward for publish), and a publisher can publish. We can divide those roles amongst people who may have different roles in different documents. All is managed through a personal queue via the Web app. Also, by being in the Python way of things, we can write some tools to glue stuff together. I'll address this below under your concerns about this three-pronged approach, and will show how we mitigate or remove the multi-tool concerns. > 3. Emacs and DocBook XML - for greater flexibility > > We can use Emacs and DocBook XML to publish our efforts in any desired > format: web pages, PDFs, Postscript, etc. The advantage of this is the > "write once, use often" approach, which is a primary tenet of modular > programming and the basis of FLOSS. These documents are also the base > for the many translations which are produced by our Translation team > members. > > ADVANTAGE: Modular efficiencies, "reuse of code", standard "code" base It is also usable as a transition state that content can automatically move through. I'll note that while people are tackling the real challenges of writing a book 100% in a Wiki, I remain quite skeptical. The longest book I've written is the Red Hat SELinux Guide, which is about 100+ pages in PDF, and there is *no way* I could have accomplished the quality and level of detail if I had to edit in a Wiki. Even if we had found a way to not have to edit via a Web browser. The reason is that a Wiki is designed for doing things easily, but in doing so it has to compress out tools that you need for a real book. For example, in DocBook XML, you can put a construct like this anywhere in the content : <indexterm> <primary>Customizing</primary> <secondary>Desktop background</secondary> </indexterm> <indexterm> <primary>Desktop wallpaper</primary> <see>Customizing</see> </indexterm> Believe me that when you learn to do this with Emacs, it is really, really easy (several keystrokes to put in the skeleton, fill in the terms, move on). The toolchain then makes an index from the book during each build. The index automatically links back (in HTML output) or provides page numbers (in PDF). Something was incorrect? Fix in XML, move the term around, etc., rebuild, and the index is fixed to match. So, there are literally hundreds of advantages of using a full-featured book writing tool. And yes, that complexity comes with the price of a steeper learning curve. > There are definite disadvantages to this three-pronged approach. It > would be great if we could do everything with one tool - maybe someday > soon we will. For now, we can enjoy the advantages this approach > offers. Now here are the disadvantages, which I would rather call > challenges. With a Python programmer and a few weeks of time, below is what we intend to accomplish. This could be done at anytime, but we have to wait for Plone to be updated to do a full roll-out. 1. Write and edit in the Wiki. The Wiki either works directly on XML in CVS or on regular Wiki pages. Some pages stay where they are forever (project pages, e.g. wiki/SELinux, wiki/Packaging), and some are pre-drafts (Docs/Drafts, Docs/Beats). 2. When ready, select "Publish in CMS as draft" from the 'More Actions:' dropdown menu on the right. - If the content is XML in CVS already, the "Publish..." triggers off a build of the document into XHTML and the publication into Plone under the user's ID as a contribution at the beginning of the workflow. - If the content is Wiki, it is first converted to XML, wrapped in the toolchain, then built to XHTML and published into Plone at the beginning of the workflow 3. The assigned editor for the document receives notice of a (new) draft. They read and either send back to the writer with specific items to fix, or push on to publish. 4. When published in Plone, it is put in the proper taxonomy location and has all the slick look we can give it. The same holds true for translation. We can add a "Submit for translation" that follows a similar path. However, this button might be in the Plone workflow, and a publishing editor uses it after content is ready. > THE CHALLENGES > > 1. Complexity. > > Three tools are harder to use than one tool. Most of us know one tool > really well, some of us know two tools pretty well, and a few know all > the tools (of whom we stand in awe). For instance, I've got a pretty > good handle on MoinMoin, a desire to learn Plone, and a basic grasp of > Emacs and DocBook XML. There is also the issue of conversion from one > format to the other. > > This is why the team approach (the bazaar) is so powerful. As a > community, we are stronger than as individuals. We can pool our talent > and produce a whole greater than the sum of its parts. We also have > powerful FLOSS tools. > > SOLUTION: Teamwork, teamwork, teamwork and tools, tools, tools Ideally, a writer can choose on editor (Emacs, Vi, Gedit, Jedit, OO.org, Wiki, etc.) and a method to commit work (CVS client or via Wiki), and they are done. But we have work ahead of us to get there. > 2. Coordination of Effort. > > This is always a challenge. Many times "we have a failure to > communicate". The good news is we have great tools at our disposal: > wikis, email, IRC channels, etc. People are making good money > promoting "collaboration". We have the tools we need already at hand - > we just have to make use of them. New tools are emerging like VoIP. > > SOLUTION: Use our great FLOSS communication tools creatively Our major communication challenges is with the Translation project, and secondary with 80% of the Fedora developers. Within the FDP, we have traditionally done pretty well. Translation communication will improve when we can get CVS moved and their tools included into fedoraproject.org. Developer communication is just something we work on continuously. > 4. Dedication. > > This is a personal decision - how to invest your limited time and > resources. Again, the solution is to prioritize your life. How > important are the goals and objectives of the Fedora Project to you > personally. How has the recent news affected you? Has it made you glad > or mad, discouraged or more determined? > > SOLUTION: Up to you. There are other benefits and we should be mindful of ways to reward people in the FDP (writers/editors/translators or w/e/t). * Highlight contributors (name as author, translator) * Help people to grow their skills and related interests - I wrote about how this can positively affect career goals here: http://iquaid.livejournal.com/13095.html * Have Fedora Project bring w/e/t in for FUDCon events * Connect Fedora Ambassadors with w/e/t to present at FLOSS events * Get some of our content published as a real book * Thank you gifts * Other tangible items * ??? > FUTURE TOPICS > > 1, Upstream contribution to other documentation projects (for example, GNOME). > 2. Improvements to document conversion tools. > 3. Better communication (VoIP, online presence tools [MugShot?]) 4. Cross-stream collaboration, where we work with other documentation teams from other projects (distros, etc.) to create or contribute to documentation commons. For example, fixing up man/info pages. > To quote Dennis Miller, "This is my opinion - I could be wrong" :-) And he so often is. :) - Karsten -- Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject quaid.108.redhat.com | gpg key: AD0E0C41 ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
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
