DeveloperManual

Links

Introduction

Authors

  • Rick Spencer

Content

  • Target audience
  • Goals

The Python Language Crash Course

Authors

  • Rick Spencer
  • Ryan Macnish

Content

Creating an application with Quickly

Authors

  • Didier Roche
  • Luke Jennings (jenkins)

Content

  • quickly create
  • quickly design
  • quickly edit
  • quickly run

Building a User Interface with glade

Authors

  • Rick Spencer
  • Luke Jennings (jenkins)

Content

Creating Widgets on the Fly

Authors

  • Rick Spencer

Content

DesktopCouch

Authors

  • Stuart Langridge

Content

  • When to use desktopcouch
  • Creating databases
  • Using records
  • Using views, map/reduce
  • Using CouchGrid

Multimedia with Gstreamer

Authors

  • Jono Bacon
  • Ryan Macnish

Content

  • Using the gtk.Picture widget
  • Using pixbufs
  • Playing Audio
  • Playing Video
  • Capturing Audio/Video

Socializing

Authors

  • Ken Vandine
  • Elliot Murphy

Do we still need this chapter? -- Ryan Macnish

Content

  • Gwibber
  • U1

Informing the user with Indicators

Authors

  • Owais Lone

Content

  • Indicators with Python
  • Quickly add indicator

Tools

Authors

  • Kyle Nitzsche

Content

  • Managing your project with Launchpad
  • Version control with bzr

Distributing your Application

Authors

  • Didier Roche

Content

  • Sharing your application with Ubuntu Users
    • - quickly release + ppas + apt:// + - getting it ready for the software center

UDS Maverick Notes

== Manual Team Vision ==
 * Make a huge content pool for a whole bunch of different content that can
 be exported into what formatted is needed (maybe)
 * Have a good way for people to submit to the pool
 * Have authors not worry about whatever markup format is being used
 * The manual team have a toolchain in place which works with some markup language

== Blueprint description ==

It would be very cool to have a book which explained how to do opportunistic development on Ubuntu. This would be aimed at people with development skill (it is not to teach programming) but who do not know the best way to build and release apps for the Ubuntu platform. It will make opinionated choices, and explain best practice for development on Ubuntu, in much the same mental headspace as Quickly. It should be pleasant and discursive to read (it is not a reference book), and introduce high-value best parts of the Ubuntu platform, such as quickly, desktopcouch, application indicators, and so on.

Who decides what gets in the manual?

Make an application from scratch - what tools did you use? Those are what go in the manual.

The book should have an overall vision: each chapter explains one technology with snippets and by developing a toy application which demonstrates that technology. The whole book also develops one overall application which uses all the technologies, so that readers can see how they all fit together.

Nice feature: copy/paste some snippets into quickly and get a cool working app (even if you didn't think too hard about what each step did)
 - each chapter develops a small toy application relevant to the content in that chapter (eg desktop couch)
 - and overall book develops an application that uses them all

== The User ==
 * Has programmed, knows some programming
 * Is interested in targetting Ubuntu specifically

 * People who have just finished Dive Into Python is about the right level of programming knowledge to have: after they finish that, have them come back here

== About ==
 * The programming facilities for Ubuntu

== Table of Contents Draft ==
 * Creating an application with Quickly
 * The Python Language (Point people to Dive into Python )
 * Building a User Interface with glade
   - writing code to respond to signals from that UI
 * Composing Apps with Widgets
   - creating your own widgets
 * Creating controls on the fly
 * Displaying and controlling Media
 * Storing persistant data with desktopcouch
 * Reading and writing files with Python
 * Informing the user with Indicators
   - appindicators and windicators
 * Integrating online components (scraping web sites and reading APIs)
 * Managing your project with Launchpad and Ground Control
 * Version control with bzr
 * Sharing and publishing data on Ubuntu One
 * Sharing your application with Ubuntu Users
   - quickly release + ppas + apt:// +
   - getting it ready for the software center
 * Designing a Good App (input from design team)
   - some Ubuntu design guidelines and HIG, to explain to people some of the basics of writing an app that's usable
 * Maybe notes about choosing good variable names, making code legible, indenting, etc.

^^^ best chapter titles have a technology name and what it's for (doing x with foo) rather than just the concept/tech
 * dbus apis -- if we use an individual app's D-Bus API then document how to talk to that, but don't try and document how to use D-Bus generally

Nice things to have:
 * How to use each individual technology and how they all fit together to make cool stuff
 * have each chapter explain why we've made these opinionated choices
 * a style guide for the book to make it coherent
 * editors need to let others know what part they're working on to reduce duplication of effort
 * ideal: have a code expert write the code and a writing expert learn the technology and write the chapter about the program/tech
   - possible: have a competition for the code

Prospective writers:
 - Jeremy Bicha (jbicha)
 - Scott Ritchie (Yokozar)
 - Rick Spencer (rickspencer3)
 - Stuart Langridge (aquarius)
 - Alan Pope (popey)
 - Paul Sladen (sladen)
 - Travis Hartwell (nafai)
 - Benjamin Humphrey (humphreybc)

Ubuntu online support website mockups:
http://www.flickr.com/photos/humphreybc/sets/72157623882545941/

Split into two sections, Ubuntu support and "Ubuntu Learning Centre" <<< this stuff will go into the latter.

Part of the fun of programming is being able to share with others

By writing this book and answering the questions people have about "how do I do that" we help realize what holes we still have in the development platform (what's weak/missing)
gives ideas to new quidgets

== Do and Don't chapters ==

* Examples of three choices to implement each button/menu layout with ticks and crosses for the ones that meet the Ubuntu HIG Guidelines ("opininated choices")

=== Methodology ===

* Get good coders to write fixed-length (100 lines, inc comments, without obfuscation) programs
* Get good writers (_not_ familiar) with the code to replicate it and write the chapter
*

*

UDS Natty Notes

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

DesktopTeam/10.10/DeveloperManual (last edited 2011-02-05 00:01:05 by 87-194-39-9)