Charm Quality Ratings updates

[Gary Poster]

On 09/30/2013 09:47 AM, Nate Finch wrote:
> I would recommend not making documentation an attribute in yaml.  That
> puts strong pressure on writers to make their documentation extremely
> short.  No one will want to type out a full page of documentation into a
> yaml attribute.  Far better to make the documentation into a separate
> file, to emphasize that you can write as much as you want (and more
> documentation is almost always better).

I'm not sure I agree with you here, but AFAIK the discussion is moot
unless we want to rejigger most or all of our charms.  The config
documentation is already in the YAML.

Every config element in config.yaml has a description.  A majority of
them have multi-line descriptions, which describe how to use them.
Here's one of bunches of examples.

  nagios_context:
    description: |
      Used by the nrpe-external-master subordinate charm.
      A string that will be prepended to instance name to set the host name
      in nagios. So for instance the hostname would be something like:
          juju-myservice-0
      If you are running multiple environments with the same services in
them
      this allows you to differentiate between them.
    type: string
    default: "juju"

Gary

> 
> 
> On Mon, Sep 30, 2013 at 9:16 AM, Richard Harding
> <rick.harding at canonical.com <mailto:rick.harding at canonical.com>> wrote:
> 
>     Yes, we can do this. We currently support doing markdown rendering of a
>     charm's readme in JS. Jorge, how are we looking to have users document
>     their interfaces? As a description attribute in the yaml? Could that be
>     easy to write out as markdown?
> 
>     On Mon, 30 Sep 2013, Mark Shuttleworth wrote:
> 
>     >
>     > Are there good markdown renderers in JS? Should we aim for interface
>     > documentation in MD?
>     >
>     > On 30/09/13 12:32, Richard Harding wrote:
>     > > On Wed, 25 Sep 2013, Luca Paulina wrote:
>     > >
>     > >> On Wed, Sep 25, 2013 at 3:06 PM, Jorge O. Castro
>     <jorge at ubuntu.com <mailto:jorge at ubuntu.com>> wrote:
>     > >>
>     > >>> Hi everyone,
>     > >>>
>     > >>> I'd like to revise the charm quality stuff a bit, mostly the
>     ~charmers
>     > >>> have captured that we would like to encourage folks to
>     document the
>     > >>> interfaces in their charms and I'd like to add that as a charm
>     quality
>     > >>> bullet item.
>     > >>>
>     > >>> In the past that just meant getting a +1 from some charmers and
>     > >>> editing the docs, but now that we have a GUI I want to make
>     sure we
>     > >>> don't add things to the guidelines and not sync up with the
>     GUI and
>     > >>> design teams, so what would be the best way for me to drive that
>     > >>> forward?
>     > >> Thanks for the email Jorge, maybe we can find sometime to
>     discuss it
>     > >> tomorrow over a hangout. There is a need to revise the copy of
>     the intro
>     > >> paragraph as well, we should discuss that at the same time.
>     > >>
>     > >> Thanks,
>     > >>
>     > >> Luca
>     > > Did this happen? To answer the first, question, a bit on
>     charmworld to add
>     > > the new QA item with the text and section to place it in will
>     allow us to
>     > > add it to the QA process. The Gui will then pick it up and
>     adjust scores
>     > > accordingly.
>     > >
>     > > --
>     > >
>     > > Rick Harding
>     > >
>     > > Cloud Engineering
>     > > https://launchpad.net/~rharding
>     > > @mitechie
>     > >
>     >
> 
>     --
> 
>     Rick Harding
> 
>     Cloud Engineering
>     https://launchpad.net/~rharding
>     @mitechie
> 
>     --
>     Juju mailing list
>     Juju at lists.ubuntu.com <mailto:Juju at lists.ubuntu.com>
>     Modify settings or unsubscribe at:
>     https://lists.ubuntu.com/mailman/listinfo/juju
> 
> 
> 
>