kubuntu ubuntuguide version
sean at inwords.co.za
Wed Apr 20 07:58:10 CDT 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
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.
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
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
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
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 at inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 189 bytes
Desc: not available
Url : http://lists.ubuntu.com/archives/kubuntu-devel/attachments/20050420/2ab84434/attachment.pgp
More information about the kubuntu-devel