Juju Documentation

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