[wp-docs] New WordPress Handbook

Fri Jan 23 23:52:50 GMT 2009

I read Mike's comments with a lot of enthusiasm because he communicated the
whole DITA concept and benefits with a lot of clarity. I was especially
intrigued by his statement,

"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 would love to see WordPress harnessed as a DITA authoring tool. In some
way, the structured blogging plugin (http://structuredblogging.org/) is a
step in this direction. The posts created using the structured blogging
plugging are semantically structured in a way that enables them to be
syndicated and pulled into other systems, or something to that effect. It's
the concept of microformats -- like with hcalendar. The idea is to create
content structured in a way that all systems can parse and manipulate.

DITA is essentially the same idea. Create an XML structure for help material
that breaks free of any proprietary constraints or formats of specific
software, and the information you create is then free. It can move between
systems and be manipulated into different formats and deliverables.

DITA has been the hottest topic in technical communication for the last year
and a half. There is a tremendous industry push among almost all help
authoring tools to include support for DITA.

Would it be possible to enable WordPress to create DITA-structured topics?
All it would take is some kind of plugin similar to the structured blogging
plugin (perhaps the integration of the DITA Storm editor). If you can
empower WordPress as a DITA authoring tool, *you will then enable anyone to
create a topic structured in DITA. With these topics, you could create a
DITA map (table of contents) where you could pull in the topics you want
into the books you want (e.g., advanced, beginner, CSS-based).* *Essentially,
you enable every member of the community to become a help author, without
worrying about structure or other formatting expertise.*

As Mike pointed out, DITA is not only more scalable than DocBook, it's also
more flexible. The goal is not to produce a massive printable version of
WordPress documentation, but to provide specialized outputs for different
purposes, interests, and roles.

Although I'm not a DITA expert myself, I am very well connected to some DITA
experts (as well as DocBook experts) and would like get more involved in
this project, if this is a route you're interested in pursuing.

Tom
http://idratherbewriting.com

On Fri, Jan 23, 2009 at 2:57 PM, Mike Little <mike at zed1.com> wrote:

> 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/
> _______________________________________________
> wp-docs mailing list
> wp-docs at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-docs
>

-- 
---------------------
cell: 801-822-2241
blog: www.idratherbewriting.com
twitter: www.twitter.com/tomjohnson
news: www.writerriver.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://comox.textdrive.com/pipermail/wp-docs/attachments/20090123/ccf0c63e/attachment-0001.htm