[wp-docs] New WordPress Handbook

[Mike Little]

I've waited a while to see how this conversation develops before joining in.

Lorelle (and other non technical folks) the fact that Subversion is to
be used is not really very important. It is merely revision control of
the changes. The most important thing we will get from Subversion, as
Mike and Matt pointed out, is the ability to branch the book's
'source' and to continue to develop those branches of the book
independently.

Austin you asked what problems using subversion will solve that the
wiki doesn't  - the main one is the ability to have one or more
'released' versions of the book at the same time as one or more
versions in development. A wiki is always the 'latest' version,
regardless of whether people are in the middle of updating things.
Sure you can look at past revisions of individual pages, but for
someone who wants to look at the 'current' documentation as opposed to
the half finished next version, they're stuck. You end up trying to
work around this problem with duplicated extra pages or marking up
sections of a page with a version indicator. Far from ideal.

For those assuming the process of submitting updated and new content
for a book will be in any way related to the process for submitting
code, there really is no correspondence. If you submit a patch to the
handbook that is 'wrong', at worst a paragraph or two might not make
sense, or will be grammaticality incorrect.  Whereas submitting code
that is worng means the program doesn't run or it corrupts the
database or leaves a security hole.
The two are not comparable. I also don't' expect the exact same set of
people will be involved.

Now to the important stuff: The real value of using the 'subversion
book' method is that it is using docbook to generate the output. That
is, the raw content of the book (the chapters, paragraphs, tables,
screen shots, etc.) is stored in DocBook's XML format. This has a
number of advatnages, many of which have been raised in this thread,
including supporting multiple formats, building the book on demand and
so on.

However, I need to raise some very serious problems with the
'subversion book' method.

Firstly, the subversion book is stored in just 16 files! That is each
chapter and appendix is a single file. The largest of which is 300K.
It will be impossible for multiple people to contribute to such large
pieces of work with actual patches. As soon as the first couple of
patches are applied the rest will be hopelessly out of date.

Which brings me to a  second problem. Subversion does not to my
knowledge diff xml files as xml files. That is, it does not understand
the semantics of an xml file structure. It treats them as ascii
records (lines) and that doesn't work for structured files. I am not
aware of a third party add-on that will do the job either (subversion
supports pluggable diff engines). At least not an open source one.

The upshot of which is that I do not believe subversion can be used to
directly manage 'patches' to the document in the way it is used for
code.

The files size issue could be addressed by splitting things up into
much smaller pieces (I presume DocBook supports that), but it still
doesn't solve the diff and patch issue.


So how to address that problem?

As was mentioned by Tom Johnson, I believe DITA is the correct
solution. Some background: At my last job the technical documentation
team and I came up with a solution to overwhelming documentation
demands and problems by creating a system based on DITA, Subversion,
some home grown php code, oh, and WordPress.

In a large nutshell, the DITA system breaks the content (the words in
the book) into manageable, and *reusable* chunks. Those chunks can be
as large as a whole chapter (not practical as given above) or as small
as a single phrase (which could be just one word -- probably going to
far). Most chunks are at the sub-topic level -- a couple of paragraphs
or so.

These chunks are then assembled in two ways, the first, by creating
topics which reference (and pull in) the smaller chunks to create a
topic about a particular subject.
Then those topics  are pulled to together in (a topicmap or bookmap --
like docBooks 'book' xml) to create chapters and whole books.

Now for the clever bits.

Firstly, single sourcing or re-use: wherever you have a common phrase,
or couple of sentences (a chunk), perhaps a common overview of a
subject that needs to be in several different topics (because in
reference books you do have to repeat yourself a lot), you write that
once, then reference it in all the topics it has to appear.
Got a typo - fix it once, and all the topics which reference it are
now fixed! Need to update it for the new version of WP - update it
once and all those topics are now updated.

Next: audiences and other meta data. Think of adding tags to the
content. Tags like 'WP2.6, WP2.7, Advanced-level, beginner-level,
offline, etc. You can add those at the level of an individual chunk, a
topic, or a whole chapter (in a topicmap).

So you might have a topic that begins with an intro (pulled in from a
common chunk) an overview, a simple beginners run through (tagged
beginner-level), followed by an advanced run through -- tagged with
advanced-level. Finally you tag all the screen shots with 'offiline'.

Now imagine being able to say "I want to build a beginner's manual for
version 2.6 in PDF"  - so you include chunks with tag WP2.6, exclude
chunks with tag advanced-level and include chunks with tag offline,
and build as PDF.

Or you want version 2.7 advanced manual in RTF? Include chunks with
WP2.6, beginner-level, advanced-level, and offline and build.

How about a beginners guide for on-line help use. Exclude
advanced-level and exclude offline, build as XHTML. Why exclude
offline? Screen shots don't add much to the 'help when you have the
screen in front of you.

Oh and I mentioned WordPress -- I built an importer which will take
the XHTML generated by DITA and import it into WordPress as a
hierarchical set of pages. I even have a version for WPMU that
supports populating each mu blog with separate areas of content.

Here is a link about DITA for the curious:
http://dita.xml.org/book/getting-started

Rather than have you Google search for this stuff and the lovely Miss
Von Tees show up at awkward moments, try my delicious links
http://delicious.com/mikelittle/dita

By the way, this doesn't solve the problem of diffs and patches, but
the much smaller chunks are manageable with a locking pattern rather
than copy and merge (I know its sacrilege to use Subversion in that
way!)

Hope this gives some food for thought. I have a whole load more on
process, standards, user contribution mechanisms and the need for
control.


Mike
-- 
Mike Little
http://zed1.com/