Charm Quality Ratings updates

[Gary Poster]

On 10/03/2013 01:50 PM, Mark Shuttleworth wrote:
> 
> Are we talking about documentation of the config (lightweight) or
> documentation of the whole interface, for development purposes?

Ah, thanks.  I was obviously speaking of the former, but after
re-reading the start of the thread, it seems Jorge was discussing
documentation of the whole interface.

I think that whole-interface documentation should be outside of a charm,
because mutiple charms can fulfill a given interface.  In that case,
doing what Jorge seemed to be suggesting initially--putting it in the
primary Juju docs--seems the right way within our current doc world.  We
don't use YAML for that, so Nate's point is good.

Gary

> 
> 
> 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
>>>
>>>
>>>
>>>
>>
>