Juju Documentation

Registered by Jorge Castro on 2013-10-15

Juju Documentation
============

Problems with documentation
---------------------------------------------

- Features land without docs
- developers don't like writing docs
- web docs get out of sync with e.g. juju help
- developer docs also need to be published (i.e. not user facing, but architecture type notes
- docs need to be easily ingestible into new 'one juju site to rule them all'

Discussion points
--------------------------

Should docs be located in juju-core?
    Advantages: easier to enforce docs of new features
    Disadvantages: User facing docs should be of finished, stable features
    Decision: Docs should not, at the moment, be included in juju-core

Should Docs be generated in markdown/sphinx/docbook/etc?
    Advantages: developers would find it easier to submit/review docs
    Disadvantages:
      * Everyone has their own preferred system - whichever is chosen, everyone else would hate
       * Includes an extra step to generate the format we need to consume
       * None of the alternatives natively support features the current docs rely on.
  Decision: Docs should remain in HTML for the present. We should investigate ways of making it easier to manage.

Still to be determined
--------------------------------
Mechanism to alert docs maintainer when user-facing features are changing

Blueprint information

Status:
Complete
Approver:
None
Priority:
Undefined
Drafter:
None
Direction:
Needs approval
Assignee:
Nick Veitch
Definition:
Obsolete
Series goal:
None
Implementation:
Started
Milestone target:
None
Started by
Nick Veitch on 2013-11-11
Completed by
Katherine Cox-Buday on 2015-06-11

Related branches

Whiteboard

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.