On Fri, Jan 31, 2014 at 5:34 PM, William Reade <[email protected]>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 < > [email protected]> 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 >> [email protected] >> Modify settings or unsubscribe at: >> https://lists.ubuntu.com/mailman/listinfo/juju-dev >> >> >
-- Juju-dev mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju-dev
