Trinity User Guides Redux

A while back we discussed Trinity user guides. My schedule now looks good for digging deeper into providing that support. I also have reconsidered some elements of our past discussion. A proposed outline/table of contents will follow in another email. This is a lengthy read. I hope to receive commentary and discussion, but take your time to read and digest. :) ==================== Recap: ==================== We wanted to use a format that was easy to merge revisions into the GIT tree, which meant some kind of text based file system. We leaned toward ODF/ODT because the underlying file format is XML. Additionally that format lends well to anybody who wants to get involved because any word processor supporting ODT could be used. We want to support two output formats: PDF and HTML. PDF is important for portability. HTML is important to host online versions of the guides. Further, I envision us adding a TDE Handbook "device icon" that is a link to a local copy of the TDE user guide (kdebase?). A default new profile would have that icon on the desktop. We could have a T-Menu option for the guide too. KWord supports ODT, which supports the "eat your own dog food" philosophy. (We discussed that KWord's ODT support needs updating, but that is a different discussion.) Using KWord allows community members to participate with helping with documentation. I don't anticipate serious problems with contributors using the current KWord ODT "as is" because they will not be using complicated formatting. Further, we are not concerned with compatibility with other word processors. (Would somebody use Abiword to contribute to Trinity documentation?) Any user wanting to report typographical errors can copy and paste into their email client. If we use KWord to maintain the documentation, we noted that PDF output was not an issue because of the built-in PDF printing that comes with TDE. (Use File/Print rather than look for any 'PDF Export' or 'Save As' feature.) We more or less left the discussion with maintaining the guides in ODT format. Is that a good decision? I have been involved with technical writing for more than two decades. Word processors succeed in that environment only when custom templates are used along with a robust set of style tags. Allowing any manual formatting at all is a management and editorial nightmare. Although most people are familiar with using a word processor, only a minority of people outside of technical writers are familiar with templates and style tags. In the past whenever I designed templates for customers, I removed the manual formatting buttons from the toolbars and respective menu options. No manual formatting is allowed in any serious tech writing project. Further, there is a well known challenge with using a word processor to maintain our guides: generally, HTML output is awful and gets cluttered with useless tags. Any HTML we generate must validate all the time. I never have used a word processor that can provide that kind of HTML. There always is cleanup required. Certainly we could do that: maintain the guides in KWord and use some scripting to scrub the HTML. All of this sounds messy and labor intensive. Is there another way? We discussed the idea of using a markup language. Generally we were not in favor of using a markup language. One reason is the simpler markup languages do not support complicated features such as tables, text flows around graphics, etc. Another reason is we want to encourage community involvement and markup languages do not provide a familiar WYSIWYG interface. ==================== Proposal: ==================== There is one markup language that supports our GIT goals as well provide formatting flexibility: DocBook. DocBook is a subset of XML and popular in the free/libre world. A challenge with DocBook is few everyday users are going to use a markup language to contribute to documentation efforts. That should not be a problem because we agreed in our discussions that non team contributors can use whatever they want to submit revisions. They submit revision changes to the Trinity documentation team. Somebody on the documentation team would edit those submissions according to a Trinity style guide, convert those submissions into whatever format we use, and then merge to GIT. Sounds much like our first discussion: markup or word processor? Both. For community members who want to help with documentation, we create a KWord ODT template with known style tags. If possible we design the template toolbar and menus to prevent manual formatting. A premade template will satisfy our desire to make the process easier for community members. A template and style tags provides consistency. Because many people are unfamiliar with using style tags, we write a how-to. Using style tags is easy and after people see how style tags operate they wonder why anybody would use manual formatting for any serious project. Because the document template is based on style tags and not manual formatting, we use some scripting to convert that ODT/XML document to our DocBook templates. By the way, KWord 1.6 provides only nominal exporting support for DocBook (http://userbase.kde.org/Kword/1.6/DocBook). Some scripting attention would be needed to convert such documents. Yes, we could use that same template for our documentation team and maintain our user guides in that format. But we lose flexibility and we still have to scrub the files to validate any HTML output. But guess what? We have to use DocBook anyway --- for our Handbook help files. :) All of the TDE Handbook help files are in DocBook. Yes, all of them need serious revision attention, but that too is another discussion. The point is one way or another we will get our feet wet with DocBook. Why not include our user guides too? I envision down the road where we establish an ability to create user guides, help files, and other small "job aid" all from the same source files. Using such document sources means we could one day host all of our documentation on our web site in real time from the GIT tree. Using KWord for that kind of single sourcing would be cumbersome. KWord should be a stop gap only for community members who want to help but don't want to deal with DocBook. When done correctly, DocBook files can be massaged into high quality professional documentation, both PDF and HTML. As evidence, I recommend anybody interested in this topic to browse the OpenSuse KDE3 user guides (http://www.novell.com/documentation/opensuse103/). Both the PDF and HTML versions of their documentation are maintained with DocBook. As far as I can tell, just about all of the documentation teams working for the big distros use DocBook. Our user guide discussion reduces to what people on the Trinity documentation team want to use. I want to consider DocBook. In addition to making revisions with GIT easy, DocBook is neutral about outputs because that is controlled by backend processing. DocBook provides longevity. DocBook files are not affected should KWord no longer be supported in Trinity, which has been discussed. We have to deal with DocBook anyway because of the Handbook help files. Most of what we need is already available. All we need is to learn the processes. Oh, and document them too. :) ==================== Challenges: ==================== 1. Editing. Ideally we find a free/libre XML/DocBook editor that supports WYSIWYM (What You See Is What You Mean). WYSIWYM is different from WYSIWYG (What You See Is What You Get). The latter includes actual final page formatting directly on the screen. WYSIWYM does not. The focus with WYSIWYM is structure, which is exactly what DocBook supports. Yet an attractive feature about using a WYSIWYM interface is the writer sees some sort of visual representation of the text structure rather than raw markup. Think of WYSIWYM as a pseudo WYSIWYG. The visual feedback helps. Without a WYSIWYM interface, writers work in raw markup, which is not easy for many writers to do. There is the debate about eating one's own dog food. Trinity provides Quanta Plus. Quanta Plus supports DocBook (http://l10n.kde.org/docs/doc-primer/quanta.html) and is a well regarded tool for web development. Yet unlike HTML, Quanta Plus provides no WYSIWYM interface or display feedback for DocBook. That means writers on the documentation team learn to work in raw markup mode. Probably not a huge obstacle because the number of people on the Trinity documentation team will be but a few. I will ensure we have good documentation to use that tool for our specific needs. Yet with Quanta Plus we have a tool to claim we eat our own dog food. I'm not sure, but I think the KDE3 documentation team used Quanta Plus. I don't know what the OpenSuse documentation people use. (I'm curious to know.) I'm willing to overlook that Quanta Plus does not provide a WYSIWYM interface or display. Perhaps I'll add an enhancement request for that. :) Basically, most, if not all of these WYSIWYM interfaces use some kind of style sheet to interpret the underlying DocBook into basic HTML for the visual presentation and vice-versa. Remember that WYSIWYM is not a representation of final formatting but a visual representation of the document structure. Working in WYSIWYM is easier for most people than direct markup. Would be nice if we could add that feature to Quanta Plus. Although writing in raw markup --- even with Quanta Plus --- has a geek aspect that appeals to some, in the long term a WYSIWYM interface would be a great asset. Anybody up to the challenge? :) If we don't eat our own dog food, there are several commercial XML editors that provide a WYSIWYM interface. Some provide free-to-use versions but are closed source. However, one such editor is GPL(3): Syntext Serna Free (http://www.syntext.com/products/serna-free/). For professional reasons I intend to look at that tool. Serna Free is the only professional XML editor supporting DocBook I know that is free/libre. The sources are available online. Serna Free uses Qt4. :( Deb and rpm packages are available as well as a generic install script. Quanta Plus should be our first choice. We make do until Quanta Plus receives a WYSIWYM display like that provided for HTML. :) Quanta Plus provides some validation tools. Quanta Plus does not provide the full backend support that Syntext Serna Free provides, but we'll learn that backend processing support, which I discuss next. :) 2. Backend processing. Minimally, Docbook backend processing requires xmllint and xsltproc. The former to validate the code and the latter to convert to HTML and PDF. Both tools are available on all distros that TDE can run. Yet we do not have our own style sheets or DTD (Document Type Definition). A challenge with any generic default xslt backend support is the resulting documents are bland --- ugly and seldom flow correctly. For example, paragraph headings often get split across pages from the first paragraph. To produce professional documents requires serious hand tweaking of the xslt backend. I haven't done that but I want to learn. The OpenSuse folks use the Novell novdocx.dtd. The license is free/libre. Fortunately I found a copy of the Novell backend package containing the DTD and style sheets, XSLT scripts, etc. I haven't any idea yet how to install or use the tool chain, but I have them downloaded. Because the backend processing scripts are available in that package, with a learning curve we should be able to use them to produce both professional PDF and HTML documents and avoid the xslt tweaking process. :) Although I understand the principles of all that is involved, I never have used this tool chain. Maybe we can find an OpenSuse documentation team member who still has a soft spot for the KDE3 tradition and is willing to help us bootstrap our documentation project? Anybody using OpenSuse know such a person? :) 3. Content. I have copies of some excellent KDE3 user guides, which include the last OpenSuse KDE3 guides. I found and downloaded the DocBook sources for the OpenSuse 10.3 guides, which was the last guide to address KDE3. All of the guides I have are under free/libre licenses. We can use the content of those guides for a significant portion of our own user guides. I need to learn how to install those DocBook sources in a way to use Quanta Plus for editing. We will need to replace many of the screen grabs. We lack a style guide. Style guides provide guidance for formatting, syntax, etc. I see no reason to reinvent wheels here. The OpenSuse KDE3 guides are quite professional. I also have a copy of the KDE style guide and author's guide. All of that documentation is free/libre. We should adopt those style guides and DTD. I started an outline/table of contents for our guides. My initial effort will be to plug-and-chug existing content into that outline. Then replace screen grabs. Then edit and proofread, something I have been doing for years. After the Docbook files are ready, they can be uploaded to GIT. From then on anybody can make changes. Further, we should be able to adapt all of the backend scripting support so we can produce guides in real time. ==================== Summary ==================== I propose we use DocBook to maintain our user guide sources. We use the OpenSuse DTD and processing scripts. Familiarity with DocBook allows us to also start revising the Handbook help pages, which is much needed. We use the OpenSuse and KDE style guides. We use existing free/libre KDE3 user guides as a foundation for our guides. We provide full credit to all in our Credits section. Like the OpenSuse guides, I recommend we provide both a Quick Start Guide and a comprehensive user's guide. For community users who want to help with documentation, we design a KWord template with a set of style tags. We provide a how-to for using the template. We create some scripts to convert those documents to DocBook. I already have stated I am ready to be the grunt person to get our documentation started. Please add to this conversation! :) Darrell