<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Fri, Jan 31, 2014 at 5:34 PM, William Reade <span dir="ltr"><<a href="mailto:william.reade@canonical.com" target="_blank">william.reade@canonical.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">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.</div>
</blockquote><div><br></div><div>Most definitely, we should coincide doc updates with the stable release. Also agree on segregation.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr"><div>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].</div>
<div><br></div><div>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.</div>
<div><br></div><div>Cheers</div><div>William</div><div><br></div><div><br></div><div>[0] as does <a href="http://maas.ubuntu.com/docs/juju-quick-start.html" target="_blank">http://maas.ubuntu.com/docs/juju-quick-start.html</a>, but I'm not sure if that's "yours".</div>
<div>[1] eg <a href="http://bazaar.launchpad.net/~charmers/juju-core/docs/view/head:/htmldocs/authors-charm-best-practice.html" target="_blank">http://bazaar.launchpad.net/~charmers/juju-core/docs/view/head:/htmldocs/authors-charm-best-practice.html</a> -- 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.</div>
<div>[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.<br></div></div></blockquote><div><br></div><div>
I would say Markdown, because GitHub Pages.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="gmail_extra"><div class="gmail_quote"><div><div class="h5">
On Fri, Jan 31, 2014 at 6:58 AM, Andrew Wilkins <span dir="ltr"><<a href="mailto:andrew.wilkins@canonical.com" target="_blank">andrew.wilkins@canonical.com</a>></span> wrote:<br></div></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div><div class="h5">
<div dir="ltr">Hi Nick,<div><br></div><div><a href="https://juju.ubuntu.com/docs/getting-started.html" target="_blank">https://juju.ubuntu.com/docs/getting-started.html</a><br></div><div><br></div><div>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.</div>
<div><br></div><div>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.</div><div><br></div><div>Cheers,</div>
<div>Andrew</div></div>
<br></div></div><span class="HOEnZb"><font color="#888888">--<br>
Juju-dev mailing list<br>
<a href="mailto:Juju-dev@lists.ubuntu.com" target="_blank">Juju-dev@lists.ubuntu.com</a><br>
Modify settings or unsubscribe at: <a href="https://lists.ubuntu.com/mailman/listinfo/juju-dev" target="_blank">https://lists.ubuntu.com/mailman/listinfo/juju-dev</a><br>
<br></font></span></blockquote></div><br></div>
</blockquote></div><br></div></div>