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