← Back to team overview

ubuntu-manual team mailing list archive

An interesting blog by Matt Zimmerman touches on docs



Which includes this tantalizing paragraph:

*"Treat data as a service*. It’s no longer useful to package up documentation in order to provide local copies of it on every Linux system. The web is a much, much richer and more effective solution to that problem. The same principle is increasingly applicable to structured data. From documents and contacts to anti-virus signatures and PCI IDs, there’s much better data to be had “out there” on the web than “down here” on the local filesystem."

With which I agree in general.
* on-disk docs might effectively be limited to only what is necessary to get started and get connected to the web (localized, of course). * run-time help links might instead display appropriate content in the browser.

What are the advantages?
* web functional richness offers numerous paths into content and many opportunities for sweet "eye-candy' design * periodically redesign web UI to bring freshness (instead of being "stuck" in same old rendered source format)
* no "help viewer" dedicated app required (use browser)
* content is more dynamic and flexible (no building packages and installing them) which means it's easier to fix errors and address key omissions * content can include (clearly labeled) user submissions in various formats: articles (reviewed and unreviewed), forums, wikis, which means official content undergoes obvious public review and feedback * in general it can provide a much easier-to-understand path for users to submit content
* minimized disk footprint

Naturally, there are disadvantages, such as:
* no internet connection = no help (beyond the minimal on-disk help)
* umm.. any other disadvantages?

So that is where I'd be putting my efforts at re-thinking docs:
* how to start building the best web-based system possible (one that supports the Ubuntu ecosystem, including regular Ubuntu releases and Ubuntu variants) * identifying the content that *must* be delivered as packages onto the disk (basically identifying the "Getting started/Getting Connected" and content)


Follow ups