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 >>> <[email protected] <mailto:[email protected]>> 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 >>> <[email protected] <mailto:[email protected]>> 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 >>> [email protected] <mailto:[email protected]> >>> Modify settings or unsubscribe at: >>> https://lists.ubuntu.com/mailman/listinfo/juju >>> >>> >>> >>> >> > -- Juju mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju
