Tag Archives: docbook

Why Write a WordPress User or Developer Manual

Posted by Jacob Santos on May 8, 2008 Comments Off

What is DocBook and the Advantages?

DocBook is an XML format, which allows for creating documents independent of any one presentational format, like for example (X)HTML or PDF. The focus is on the content and the fifth revision of the format allows for a lot more freedom for mixing XML namespaces, so it is possible to mix in XHTML when desired.

However, the advantage of writing in the DocBook format, is that it allows for easier translation. They only need to focus on the content between the DocBook XML tags and can easily convert the DocBook to XHTML or a PDF from that one format.

The other advantage is that with the latest revision of the standard has a project that works with DocBook, which allows for displaying the DocBook in XHTML format to see what the final product will be. Aside from the XSL project, I’ve found that converting to other formats are quite a bit more involved.

What is an User and Developer Manual?

The User and Developer Manual concept is very simple: you want the very brief, basic information to give to the user on every aspect of the application. Sure, it won’t be able to walk them through every possible use case, like the WordPress Codex would. Sometimes, you only need to shove the user in the right direction and the user will be able to figure the rest on their own.

That is the concept should allow for some what quick turn out when there is a new release, once the finish product is complete for the first time. Between each release, how much really changes? A few things sure, but the user functionality largely remains the same. Therefore, once the manual is complete for one version, you can just update the pieces that changed and add new sections on new features that were added and release the updated manual for that version.

So you would always have a manual for that version. When you compile the XHTML site and/or the PDF for that WordPress version, you can always release that version. When the next version comes out, you can just release a new XHTML site and/or PDF for that version. So, you would have both versions available for those who are slow to update but still want information on the older version.

The Hard Part

The hard part is filling the User and Developer Manual with content the first time. Also, if there is a major overhaul, then it will mean that major portions of the document will become obsolete and need to be rewritten.

However, I think that if such an effort were made, then it would have some merit to charge for such a document. Whether anyone would buy such a product is yet to be decided. I think in the spirit of WordPress, it should be free as the software is, but I find motivation for such a long and tedious project hard to come by when everything is done for free.

My Goal

I still plan on creating the User Manual, because I still need to do research on DocBook format and become competent in the format, so that when I need to use it for my projects, I have experience on what doesn’t work, what does work, and what the visual output will be while the document is being written. Also, I need to learn how to change the layout and design of the DocBook output, using either the XSL and PDF.

I want to learn how to create both the XHTML site and PDF and writing the WordPress User Manual will allow for enough motivation to actually accomplish that goal. If I can find enough people to continue the project or help out, then I’ll have the manual as completely free and GPL. Well, it will be GPL anyway, but I might decide to charge for the PDF.

Content

The content will consist of text (of course), pictures, and video. Going over the video capture software, I think it will be quicker, faster, and somewhat easier to build the entire manual in multiple screencasts and then use that material to create the content in the User Manual. People will value the Videos and of course the search engines will pick up the content and pictures.

I want to put all of my raw content out there for anyone to use, so that when I leave the WordPress community, someone can reuse the content to take off where I left off. I also want to give the RAW video feeds, so that someone who has a better voice or speaking ability can do a better screencast based off of my videos.

It will be a nice experiment and I look forward to it. However, I’m thinking it will be a Fall project. The Developer Manual portion is a lot more involved, so it will be free, based in parts off the WordPress Codex, and be GPL. I want to have every component in WordPress detailed in the manual and it probably will be a lot more focused with examples and more content.

I’m more torn on the Developer Manual, because the purpose will be more geared towards allowing ease of translation than anything. It belongs on the WordPress Codex sure and I’ll probably build the majority of content on there before converting it to DocBook. I’m thinking of using the WordPress Codex as the planning and organization of the DocBook, before I compile the content into the DocBook format.

Possibly Related Posts: