Jump to Navigation

BOF: End-to-end documentation

Session Summary: 
Documentation is the window through which most people usually first view a piece of software. Smooth, intuitive UIs and accurate, precise error reporting stand little chance of hitting their target without the aid of a few well planned sentences outlining intended use cases, important features, and usage instructions. Conversely, documentation that is overly verbose, vague, or misdirected encourages blind experimentation at best, and more likely abandonment. This session seeks to identify traits of good documentation for use in the development process and eventual target use. Potential points of discussion also include areas where MeeGo isn't making the grade, and what can be done to remedy the situation. Comparisons with iOS, Android, and other competitors are welcome and encouraged.
Session Abstract: 

This session is intended to be a frank evaluation of MeeGo documentation needs and current state. This should take into account various roles that a user of documentation may fill.

* Independent Application Developer - the author of the next great idle time waster (game).
* Platform Application Developer - messaging client, home screen, or other platform applications.
* Platform Developer - Qt, MeeGoTouch, platform middleware.
* Integrator - Take the "complete" package from download to device.
* End User - The man on the street, trying to use the phone/tablet/car/etc.
* Technical Decision Makers - people deciding to bet on MeeGo (or Android, or....).

Each class of user has needs that differ but are critical. Failing at any level can result in systems which will fail to meet their full potential.

Producers of documentation will also be addressed. This group includes.

* Application developers - In-app documentation, manual on the webpage.
* Product marketeers - Advertising, blogging, App-Store description.
* Professional users - product reviews, recommendations.
* Product management - high-level specifications.
* Translators

We will look at documentation tooling currently included in the MeeGo ecosystem, as well as various options found elsewhere.
Some of the categories to be considered are literate programming, translation assistants, and formatting tools.
We will also look at the different delivery channels for documentation e.g. the product webpage, inside the SDK (Qt Creator/MeeGo SDK), in-app documentation, billboards, App-Store

What happens to poorly documented products? There are a number of unpleasant possibilities, many of which can be classified as failures.
* Lack of sales/use - Nobody knows that the product exists, or why it is relevant to them
* Underuse - people buy a product, but ignore key capabilities.
* Misuse - a product is put into production in situations outside the product scope
* Overuse - a product's use exceeds design tolerances

Sessions Details

Session Presenters

cvandonderen
Jeremy Katz

The conference organizing committee has put together slide templates for presenters to use if they so choose. Feel free to take and modify as you like!