Juju Docs - SSH key requirements

[Andrew Wilkins]

On Fri, Jan 31, 2014 at 5:34 PM, William Reade
<william.reade at canonical.com>wrote:

> I absolutely agree that we should drop steps that are not necessary from
> the documentation (so long as we *do* still describe authorized-keys-[path]
> for those with more sophisticated requirements). But we can't do this while
> 1.16 is the latest stable version, lest we confuse all those users; and
> even when 1.18 comes out, we can expect that some people will still be on
> 1.16 and want to be able to see relevant documentation.
>

Most definitely, we should coincide doc updates with the stable release.
Also agree on segregation.


> On a related note, the various config-* pages still variously reference
> default-series/admin-secret/control-bucket [0], and all the generate-config
> output is out of date. This is basically the same poor experience we're
> about to hit with the ssh-keygen stuff, and AFAICT it's currently
> inescapable because (1) the docs are not separated by juju-core version, so
> the developers literally *cannot* document upcoming features in a sane way
> (2) the docs are not in the source tree; so, out of sight, out of mind and
> (3) the docs are all raw HTML, so nobody's ever going to want to edit them
> *anyway* [1].
>
> It is critically important that we convert our docs so that they are
> segregated by version, accessible to developers, and editable in *some*
> sanely human-writable format [2]. Sorry I didn't push harder on this at
> burlingame; I thought we could maybe continue as we were, but we really
> can't. Let's fix it.
>
> Cheers
> William
>
>
> [0] as does http://maas.ubuntu.com/docs/juju-quick-start.html, but I'm
> not sure if that's "yours".
> [1] eg
> http://bazaar.launchpad.net/~charmers/juju-core/docs/view/head:/htmldocs/authors-charm-best-practice.html-- less than a third of that is actual content, and the potential for
> breakage on edit is *way* too high. And going forward, the prospect of
> fixing some minor structural issue across N versions of the docs just
> depresses me.
> [2] I don't *care* which. Markdown? ReST? Something better I don't know?
> So long as it's less work that HTML, please just mandate one and be done
> with it.
>

I would say Markdown, because GitHub Pages.


> On Fri, Jan 31, 2014 at 6:58 AM, Andrew Wilkins <
> andrew.wilkins at canonical.com> wrote:
>
>> Hi Nick,
>>
>> https://juju.ubuntu.com/docs/getting-started.html
>>
>> On the Intro/Getting Started page for Juju, we say that you *need* to
>> generate an SSH key pair. This is no longer true in 1.17.x: Juju will
>> generate one for you. Juju will continue to upload the default public keys
>> from ~/.ssh, but they are no longer absolutely required.
>>
>> I'm not sure if we should reword the docs or not, but thought I should at
>> least bring this to your attention.  CC'ing the dev list in case someone
>> has an opinion.
>>
>> Cheers,
>> Andrew
>>
>> --
>> Juju-dev mailing list
>> Juju-dev at lists.ubuntu.com
>> Modify settings or unsubscribe at:
>> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20140131/4fe887e3/attachment.html>