Charm Quality Ratings updates

[Mark Shuttleworth]

Are we talking about documentation of the config (lightweight) or
documentation of the whole interface, for development purposes?


On 01/10/13 14:40, Gary Poster wrote:
> 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
>>
>>
>>
>>
>