kubuntu ubuntuguide version

Wed Apr 20 12:58:10 UTC 2005

On Wednesday 20 April 2005 08:47, Abdullah Ramazanoglu wrote:
> I think it might be better to do a separation between "documenting experts"
> and "content providers", just like a publisher and an author. This could
> boost material input considerably. An author usually just wants to
> document his knowledge/experience etc. in some format most convenient to
> him. IMHO his focus should be on what he is good at, and he shouldn't be
> burdened with peripheral requirements and overheads (docteam procedures,
> rules, docbook/xml et.al. learning curve, etc). If a simple framework
> could be established so that anyone can submit documents in -say- text,
> html, or sxw/oot format (observing a few simple rules required by the
> framework), whichever suits him, which is then processed by the docteam
> and imported into docbook, then such a setup could provide an excellent
> fertile ground for a lot of contribution. In that case, the core doc-team
> probably no more provides content but just does engineering and publishing
> (of documents), organizing (of content providers), and tracking (of both).
> Isn't it more or less what publishers do? Another analogy would be debian
> packagers (docteam) and upstream developers (content providers). Just my 2
> kurush.

Abdullah,

Thanks for you input.

While I admit there is a barrier to entry for authors to contribute 
documentation, I would just like to address some of the points you would like 
to see. Before I do, just let me say that I am currently evaluating Apache 
Lenya to address the barriers you mentioned. You may want to take a look.
http://lenya.apache.org

In preparing documention there are a number of factors that need 
consideration, many of which actually should take precedence to to actual 
writing. My focus is on the technical infrastructure. To keep this short I 
will try do this in bullet format.

1. The format for storage should be presentation layer neutral.

2. The format should be programatically accessible.

3. Content should be easily reusable.

4. Content should be granularly manageable under a revision control system.

5. Format should lend itself it easy translation processes.

6. Authors should be able to collaborate on the same document simultaneously.

7. Format should lend itself to easy, system-wide update.

8. Format should lend itself to profiling, also called conditional texts.

9. Format should lend itself to consistenant structure.

With Docbook we have all of the above and more. In addition Docbook is an 
OASIS standard and is the standard for documentation in all of our upstream 
partners. Because of this we have easy and standard interchange. 
Point-to-point explanations to the above. 

1. From Docbook XML we are able to transform to a wide number of target, 
presentation layer formats; including: XML, XHTML, HTML, LATEX, PDF, HTML 
Help, JavaHelp, PostScript, Text, RTF and more.

2. Thanks to XML we can validate our documents and ensure they are 
well-formed. In turn this means we have a way to consistently access our file 
using other programming languages.

3. Standards such as Entities, XInclude and XPointer enable us to reuse parts 
of content with having to duplicate it. This dramatically cuts down on our 
maintenance cycle.

4. Because XML is text and not binary we can manage patches to our documents 
more easily using patches. With a single command I can update the sources of 
any number of books within the repository. I can even manage separate copies 
of the books and merge changes between them with ease. This is great for 
cases where we have documents for hoary and documents for breezy and 
documents for the next revision of the distro.

5. For the translation process we use the gettext system. The translators are 
hooked on po files and we have an easy way to give them what they want and 
manage this process across versions. In addition, since Docbook has generated 
texts like captions and labels, we can transform all books in the knowledge 
that the formatted output will be completely translated. We don't have to go 
back and change the title "Table of Contents," Docbook does it for us.

6. Because Docbook is XML, we have the ability to take advantage of the 
collaborative model provided by VCS systems such as Subversion, Bazaar and 
CVS. All authors can have a working copy of the docs and hack the same 
document without 'clobbering' each others work.

7. Thanks to mechanisms such as entities and XInclude and the ability for 
programatic access, we are able to implement strategies for modularity, reuse 
that dramatically improve our ability to update and maintain documents. For 
example, if we want to change the name of the distribution revision from 
warty to hoary we need only do this in one place and all document are 
updated.

8. Using XML and XSLT we are able to program the documents so that we can get 
two or more books from the same XML file. For example, I am currently writing 
an installation guide for ubuntu and kubuntu. For this I have a single file 
and have profiled the document so that I can output various formats for each 
distro.

9. The structure and markup language enforced by Docbook enables authors to 
forget about the formatting and focus on writing. We know that a valid and 
well formed document will always look the same. Tables, itemizedlists, 
numbered lists, images, etc. are all created in a consistant way.

So Docbook has huge advantages for us. The problem is that people who want to 
write something need to have additional skills before they can start writing 
in Docbook. So we are looking at Lenya, but this system does not yet support 
structured authoring and we will been to either develop a structured editor 
for it or extend an existing editor. 

As an interim solution we enable people to write in wiki. This has its 
problems but is one way to enable people to contribute. However, this 
situation is less than optimal since it increases the barrier to all the 
benefits I have mentioned above.

What I think people have to realize is that technologies are in various stages 
of development. While the XML recommendation and Docbook are stable, the 
technologies above them are not all FOSS and have not yet evolved to the 
point where they are able to significantly break down the barrier you 
mention. However, there are some good editor solutions out there and I 
suggest you take the time to investigate them. What you want is a structured 
editor that gives you a WYSIOO interface. OOo does give you think using a 
docbook template, but I am afraid that you will not easily be able to round 
trip your editing using this method. You may also try Morphon XML Editor or 
XMLmind. Personally, I would start with VI, Emacs and get to learn the code, 
then move to one of these methods if you feel it is helpful. If these tools 
seem to old for you, look at Kate or Gedit.

Abdullah, we have helped a number of authors join the team and become 
productive with SVN and Docbook. These people have had an interest in 
learning and we understand that they do not know everything. Our approach is 
to mentor and support these people. As I say, we have been very successful in 
this respect and perhaps we can help you.

The important message here, often not understood, is that the documentation 
sources and the process for development extends way beyond the initial first 
revision of a document and beyond just viewing it on a web site. In addition, 
I think that people need to appreciate that our documentation effort in SVN 
and Docbook is still very young, less than a year.

Hope this helps.

-- 
Sean Wheller
Technical Author
sean at inwords.co.za
http://www.inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050420/2ab84434/attachment.pgp>