Opportunistic Development for Ubuntu: the Book

here are my (Kyle) notes (edited) from the uds session:

Goal:
 * create "book" that explains how the "opportunistic developer" can write applications on and for the Ubuntu platform
 * opinionated and recommendation rich: expresses "the recommended path to quick success" for the "opportunistic developer".
 * is key start-up component of developer.ubuntu.com
 * content and a tutorial/procedure for creating applications that demonstrate and exercise essential capabilities/tools
 * 1/3 of manual currently in draft stage (needs review with respect to project goals and scope as they refine)
 * 100 pages or less (hopefully a lot less. if it gets long, it is an obstacle to a quick start and should be split up)

LP Project:
 * https://launchpad.net/ubuntu-developer-manual
 * source is maintained as trunk branch there ^^^
 * email list there ^^: join the team
 * wiki specification: https://wiki.ubuntu.com/DesktopTeam/10.10/DeveloperManual

Team:
 * Mike Terry (mterry): lead
 * Rick Spencer (rickspencer): driver
 * sections authors: in wiki page but also: Stuart Langridge (desktop couch), Kyle Nitzsche: tools, localization/translation, as needed
 * reviewers: Mike Carifio (carif) (need more)
 * testers: Mike Carifio (carif) (we need more): verify you can make the apps and do all steps as instructed
 * technical writer: TBD (see below on this person's role). Maybe Shaun McCance (gnome docs team lead)?

Source format:
 * tex/latex

Output formats:
 * pdf
 * html
 * mallard?

Localizable:
 * required
 * to be translated in LP
 * translators: Ubuntu Translators?

Schedule:
 * planning sprint (two day?) to kick off with goal of defining outline, assignments, detailed schedule, deliverables), as soon as reasonable
 * draft releases to coincide with natty alpha/beta releases (releases will facilitate evangelism/publicity/excitement)
 * released with natty
 * note: schedule will require explicit review/testing cycle followed by fixes

Builds:
 * will produce weekly builds (localized pdfs/html?)
 * can build locally

Target audience:
 * opportunistic developer. They measure their learning by what they can get done. They don't need/want to first analyze frameworks or do extensive research, they GO for it.
 * maybe just learned some python
 * don't know packaging
 * want to a) create and b) distribute

Tone:
 * light/fun/engaging and authoritative
 * not reference style
 * short sentences/paragraphs
 * use bulleted lists, numbered steps, graphics/images (screen casts?)
 * as short as possible, as long as necessary (use the same discipline when adding words as one does for adding code: for *exactly* the same reasons)

Style guide:
 * there are apparently three style guide (ubuntu manual, ubuntu docs, something else?) mterry to review.
 * goal of this is to a) clearly state tone (described above) and b) show standards ways of doing things like figures, links, lists, chapters, sections, paragraphs.
 * it should be SHORT and REQUIRED reading for authors: enforceable

Content:
 * see wiki listed above
 * full outline is a key deliverable of the proposed sprint
 * introduction: Rick Spencer wrote a draft one. needs review and probable refinement
 * 1/3 of manual currently in draft stage (needs review with respect to project goals and scope as they refine)

Content questions raised at uds session:
 * how many apps should the user create: more than one - repetition is good
  * hello world
  * media app
 * apps to exercise core dev and ubuntu items:
  * quickly
  * desktop couch
  * indicators
  * bzr and bzr ground control
  * lp with translations
  * accessibility
  * more (TBD)

Content: Accessibility:
 * author: Kyle
 * should reference accessibility as a "first-level member of the Ubuntu ecosystem".
 * will point to accessibility portal for more info (Kyle has contacted Penelope Stowe, accessibility lead, who has agreed to provide this)
 * will list high-level accessibility dos and don'ts (like don't only use color to differentiate). Need to get this list from accessibility folks. (Penelope Stowe will provide this)
 * will note accessibility is built-in for standard apps, but critical
 * will provide quick tests for accessibility developer should always use (hearing impaired, vision impaired, (maybe physically impaired?)): (Penelope Stowe will provide this)

Content: Localization:
 * author: Kyle
 * should reference localization as a "first-level member of the Ubuntu ecosystem."
 * will note internationalization/localization is built-in for standard apps
 * will list high-level dos and don'ts (kyle to provide)
 * Other key points summarized, including LP project enablement/steps, translation community
 * will provide quick tests developer should do to verify their app works in other locales with (fake/test) translations

Content: Relationship to software center:
 * the expected end result of opportunistic development is:
  * push to software center
  * push to project ppa for distribution to colleagues, friends, co-workers, etc.
  * both of these need to be covered at high level
 * software center requirements summarized: Mterry to get this

Expose the awkward bits:
 * this project will expose bits of process that are currently awkward/confusing
 * some may be fixed during this project, some later
 * guiding principle: if it is difficult to explain, it could/should probably be improved/simplified

APIs and API references:
 * sample apps will add functions and exercise APIs.
 * explanations of used API calls simple and short
 * references to API reference materials provided (for example: For more information about GTK in python, see: )http://www.pygtk.org/docs/pygtk/index.html)
 * This book is the "quick path to success," not reference docs

Related activities:
 * Martin Owens said he will be making lesson plans for each chapter for folks who will want to teach it. Those plans may include lists of take away key points students should have learned from each section.

Technical writer/editor role:
 * proposed technical writer to pull content (created by subject matter authors) together to create unified tone, ensure proper flow, enforce discipline, normalize grammar and usage
 * should come to planning sprint