DoctorMo's Blog

I hear that there is still friction between the Ubuntu Manual team and the Ubuntu Docs team.

I can’t see why, the wiki documentation is a great resource and while it has problems that stem from it being a wiki system, it’s been useful to me and to a lot of people I know. The most important parts of it are kept up to date even though it’s been criticised for becoming out of date too easily and for people to be mislead easily into following guides for older versions by mistake.

On the other hand the Manual team is new, brand new and has all the passion of a bright and eager team that might be able to make some nice documentation for Ubuntu which should be fairly easy to share back to the wiki and the Docs team in general. The manual team is also concentrating on a definitive, narrow band guide to be published on release for new users to get to grips with Ubuntu. It’s non rolling release really separates it from the Doc Team’s work and is perhaps a drawback in our ever changing work. But I think as long as each manual release is very clearly labelled, they should avoid that problem.

But even if the two teams end up sharing 90% of their content, the production of the result is where the work is going to be. I mean I think that some content from docs and manual is most certainly going to end up in some of the learning team’s classes and visa versa, but there is work there in each team which isn’t relevant to it’s peers. I don’t expect docs or manual to write quizzes or demonstration lesson plans for teachers, nor do I really expect the docs team to write all the tools and organise the compartmentalisation that will be required to produce a self contained manual.

It’s also likely that the intonation and pacing of each document source is going to be different anyway, just because the expectations are going to be different. We’re planning for, in the learning team, on being able to pull data in from other sources, but we don’t expect to be able to pull it in with a simple automated copy. It’s expected that an editor will have to go through it anyway.

What are your thoughts? Is there too much duplication? Is the manual project a sub-section of the Doc’s Team work?

A few weeks ago we started really getting into which formats might be better for learning materials for the Ubuntu Learning project. Currently I’ve been writing each class in ODF (Open Document Format) but it became apparent that while it was very easy to edit documents like this, it was very hard to integrate them into translations, diff generation, style guidelines and so on.

So I asked a very good contributor to the Ubuntu Learning project, BiosElement to do some research into various formats and he’s reported back with some findings. I want to distribute these findings to the wider community because I know how useful they will be to other documentation groups. This is a very basic summery:

And now for the meat of the report:

Open Document Format

ADVANTAGES: Pre-Installed on Ubuntu, Open Format, Ease of Editing

DISADVANTAGES: Currently impossible to use with bzr or version control, Difficult to keep consistent styling, Any changes to styles will result in large amounts of labor to update previous courses.

SUMMERY: .odt would be very difficult to keep updated and consistent but is very easy for course creators.

Plain Text

ADVANTAGES: Universal format, Everything from a cell phone to an expensive toaster can read text files. bzr and VCS systems can highlight per-line changes Text-to-Speech works well with it and it is more accessible for those with disabilities.

DISADVANTAGES: Dull, sometimes hard to read, doesn’t support any kind of styling.

SUMMERY: Easier to maintain then .odt but the lack of styling makes it a poor choice.

Sphinx

ADVANTAGES: Same as those of Plain Text with the addition of styling using Restructured Text.

DISADVANTAGES: Limited translation support, Must be compiled into .html.

SUMMERY: Not a bad choice but it has limited use outside python projects. Lack of translation support is a major future problem if used.

DocBook

ADVANTAGES: Universal format used by many book publishers. Very supported for conversion into other formats.

DISADVANTAGES: XML is very difficult to write, very complex, hard to read and simply not user-friendly.

SUMMERY: Good choice, but the difficult syntax and lack of WYSIWYG Editors creates a massive barrier to entry.

AsciiDoc

ADVANTAGES: Same advantages of DocBook with the addition of text editing and an easier to read format. Can be converted into DocBook.

DISADVANTAGES: Some may find editing .txt files hard, but I’m not sure there’s any way around this.

SUMMERY: IMO the best choice as it gives all the advantages of DocBook without the difficult syntax or learning curve.

There you have it, please get in touch with us on our mailing list or irc channel if you’ve got any additional ideas and formats to try out.