Improve Juju Documentation

--- 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
       Local provider configuration
       OpenStack provider configuration
       EC2 provider configuration
       Rackspace
       New Providers
   Deploying a Charm
       Exposing A charm
       Implicit Relations
       Machine Constraints
 * User tutorial - rename to “Using Juju” (should be embeddedd per topic)
Charms
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

Reference Guide
  Full table of all charm attributes
  Full table of all juju commands
  example: http://developer.android.com/reference/packages.html
  Glossary -appendix
  Operating Systems - appendix stuff
  Relation references - appendix stuff

Evaluate for removal:
-move-
     About juju - *move to juju.ubuntu.com.
-delete-
    Frequently Asked Questions - DELETE THIS, link to autogenerated FAQ at AU.
    juju modules - remove Juju core specific
    Drafts - REMOVE.
-content should be covered-
    Implementation details - (should be in reference guide for charm attributes)
    Commands to work with relation settings and membership (be sure to cover in charm author)
    Upgrades - both (be sure how to implement charm upgrade hooks are covered in charm author)
    Charm Upgrades (be sure to be covered in Charm Users: deployment)
    New relation-ids hook command -(should be covered in charm author)

# Documentation Framework (Courseware)

https://juju.ubuntu.com/docs/charm.html
    -Make sure to review the docs point, and have a corrolation betweeen user jouneys and screen casts.
    - Put screen cast in docs
    -screen casets and docs should reference each other.

0 -- New to Juju
1. [user] Installing and configurating Juju
 i. https://juju.ubuntu.com/docs/getting-started.html
 1. Charm Introduction
   i. https://juju.ubuntu.com/docs/charm.html
1. Charm Discovery/ Charm Store
  i https://juju.ubuntu.com/docs/charm-store.html
1. [user] Deploying your first charm (include constraints)
 i. https://juju.ubuntu.com/docs/user-tutorial.html

1. [user] How to use relations
    creating relations
    removing relations
1. [user] Service configuration/Lifecycle managment: Using the configuration.yaml & "juju set"
  i. https://juju.ubuntu.com/docs/service-config.html

1.[user] Scaling services
1. [user] Debugging deployment - debug logs and friends
1. [user] Advanced topics (deploy-to, "jitsu" and friends)
  -need to confirm how plug-in model is in Juju 2.0

1- New Charm Author
Review https://juju.ubuntu.com/docs/write-charm.html

1. Submitting your first contribution to a charm
1. Writing a new charm from scratch.
  i. https://juju.ubuntu.com/docs/write-charm.html
  a. charm tools
  a. meta-data/readme/licensing/examples/description/how to use/why to use from Ops or Dev perspective
  a. Hooks
  a. relations
     i. interface
     i. requires
  a. testing
1. Publishing to the Juju Charm Store
1. How to improve your charm using community quality ratings (https://juju.ubuntu.com/docs/charm-quality.html):
        a. Reliability
        b. Security
        c. Flexible
        d. Handle Data
        e. Scalability
        f. Ease of deployment
        g. Responsive to devops needs
        h. Upstream-friendly.
1. Getting your work peer reviewed
1. Charm Debugging

[USER STORIES]
- Someone hears about Juju and wants to try it out- they start by reading the docs, and are soon producing world-beating charms and running services which can cure cancer and solve the energy crisis.
[ASSUMPTIONS]
[RISKS]
[IN SCOPE]
- User guide to get new users up and running
- Author's guide to help people write better charms
[OUT OF SCOPE]
[USER ACCEPTANCE]
- there will be fewer questions on ask.ubuntu about juju which aren't immediately answered by pointing them to a relevant part of the docs
[RELEASE NOTE/BLOG]

[Notes]
 -Embed into docs in the same topic section & have a one general Best Practice section for users and charm authors.

 -Ensure how to become a charmer docs are more explicit: https://juju.ubuntu.com/community/charmers/
https://juju.ubuntu.com/docs/charm-store.html

---
Notes from vUDS 1305: http://pad.ubuntu.com/uds-1305-servercloud-s-juju-docs
Notes from vUDS 1308: http://pad.ubuntu.com/uds-1308-servercloud-s-juju-docs
---

[notes from cloudsprint 2013-05]
--------------------

Current docs suck, let’s redo them
- Nick has a pre-beta of new-docs: http://www.evilnick.org/juju/getting-started.html
- All in HTML so we don’t have to deal with meta-languages.
- lp:~evilnick/juju/go-juju-docs
- lp:juju-core/doc/*.txt - a bunch of fairly unorganized but very useful internal developer docs that can be helpful (incl. glossary) to evilnick when writing the more end-user friendly docs

mthaddon’s biggest concern, keeping it up to date.

Work items:
[evilnick] Define structural elements of HTML5 doc: DONE
[evilnick] Create sample "getting Started Guide": DONE
[marcoceppi] Prepare rollout strategy for new docs launch: DONE
[evilnick] Create video/webinar strategy: DONE
[marcoceppi] Propose policy for inclusion of doc contributions as ~charmers contrib: TODO
[jorge] Streamline contributions process in documentation: TODO
[mark-mims] Testing structure for charm documentation: TODO
[marcoceppi] Auto-generate charm interfaces documentation: TODO
[jorge] : Make sure our docs are synced on readthedocs.org: TODO
[jorge] Migrate/Move documentation embedded in juju.ubuntu.com into juju.ubuntu.com/docs (getting started, and community).: TODO
[arosales] Get a beta site going for Juju docs.: TODO
[arosales] Get a permanent staging site for the docs: TODO
[jorge] Get UX testing on the docs: TODO
Document local povider: TODO
Document debug-hooks: TODO
Document deploy --to: TODO
Document --constraints: TODO
Document Charm Helpers: TODO
Document Charm Tools: TODO
Document Amulet: TODO
Review drafts from previous docs: TODO
Bring in content from juju-core/doc: TODO
Embed searching into the docs: TODO
Stack Tack integration: TODO
UX feedback on docs: TODO
Improve contributing to the docs including local setup: TODO
More examples from flagbearer charms: TODO
Document juju for private clouds: TODO