[Blueprint servercloud-1303-juju-docs] Improve Juju Documentation

Nick Veitch nick.veitch at canonical.com
Tue Mar 19 15:52:14 UTC 2013


Blueprint changed by Nick Veitch:

Whiteboard changed:
  --- UDS 1303 Discussion ---
  PAD URL:  http://pad.ubuntu.com/uds-1303-servercloud-1303-juju-docs
    -Leave behind RST!
    -pandoc doesn't support some of the newer HTML5 elements (asides, etc)
    HTML5 w/ JavaScript it is!
    -Make sure juju.ubuntu.com landing page tell Juju story well (what is it, why should I use it)
    -Dynamic Content
      -Screencasts
      -Code Examples
      -Better references in sidbars with improved navigation
      -Annotate Juju deploy command
      -Annootate Juju GUI deploy
      -Annotate anatomoy of a charm
  
  --- Ideas ---
  Good examples:
   *stripe.com (https://stripe.com/docs)
     -good journeys
     -not overwhelming
   *http://developer.android.com/sdk/index.html
     -ttp://developer.android.com/tools/workflow/index.html
  
  Would like to have good sidebar notes, screen shots, tips, and examples.
  
  Would like to have knowledge of what I am at in a journey
    *Getting Started (Juju deploy)
    *Charm Development
    *Charm Deployment
    *Charm Discovery
    *Charm Debugging
  
  Model magazines
    *Wired
    *Linux Format
    *Content rich
  
  Need version control
  Want Markdown not RST
  Get rid of anything marked draft
  Need organization of what we currently have.
  Evaluate Pandoc instead of Sphinx
  Discuss GUI and Charm Browser
  
  --- Immediate Needs ---
  Verify the usability of docs (are the instructions correct).
  Identify a model for the docs (framework)
    *Not docbook - too complicated and print-biased
    *Sphinx? Needed since core is now Go?
    *Something markdown based?
    *simple HTML5?
  Milestone
    *13.04 default for Go
    *How to use it
    *Transition
      -Differences
      -Py and Go living together
  
  --- Organization ---
  
  juju users:
  Getting started
  User tutorial - rename to “Using Juju”
  Charms
  Implicit relations
  Machine Constraints
  Exposing a service
  EC2 provider configuration - all the provider stuff should be in one section
  Local provider configuration
  OpenStack provider configuration
  The Juju Charm Store (for users)
  Handling common errors
  
  charm authors:
  Writing a charm
  The Juju Charm Store
  Charm Testing
  Hook debugging
  Charm Store Policy
  Charm Quality Rating
  Debugging
  
  Evaluate for removal:
  About juju - remove.
  Frequently Asked Questions - DELETE THIS, link to autogenerated FAQ at AU.
  juju modules
  Implementation details - appendix
  Drafts - REMOVE.
  Glossary -appendix
  Commands to work with relation settings and membership
  Upgrades - both?
  Charm Upgrades
  Operating Systems - appendix stuff
  Relation references - appendix stuff
  New relation-ids hook command -?
+ 
+ TO DOs:
+ Define structural elements of HTML5 doc (evilnick)
+ Create sample "getting Started Guide" (evilnick)
+ Create list of screencasts (jorge, evilnick)

-- 
Improve Juju Documentation
https://blueprints.launchpad.net/ubuntu/+spec/servercloud-1303-juju-docs



More information about the Ubuntu-server-bugs mailing list