Document Formats for Learning Materials

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:

doc-format-research

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.