Juju Docs - SSH key requirements

[Nick Veitch]

On Fri, Jan 31, 2014 at 1:03 PM, Nate Finch <nate.finch at canonical.com> wrote:
> +1000 on version-specific doc pages.  Most other similar projects do this
> already.  Given that our stable releases are getting spaced out somewhat
> more than they had been, it doesn't seem too burdensome.
>
>
> On Fri, Jan 31, 2014 at 4:34 AM, William Reade <william.reade at canonical.com>
> wrote:

(1) the docs are not separated by juju-core version, so
>> the developers literally *cannot* document upcoming features in a sane way

Skip ahead to my proposal at the end.

>> (2) the docs are not in the source tree; so, out of sight, out of mind and

I am happy to have the docs in the source tree, but nobody else wanted that!

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

That is why there are templates. All the header and footer stuff is
necessary to fit in with the j.u.c website, it is static on every page
and is easily changed across all pages by editing a template and
running a script. I can't see if there is any other magic way to do
that, but the header and footer stuff doesn't need to be in any new
page you generate, only the placeholders.


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

We did have this discussion, at the vUDS in May 2013. There was a
session on it, and the outcome was that we should generate the docs in
HTML.

What we also discussed was that I would be informed, by some method,
whether it was bug reports or emails or whatever, whenever changes to
user-facing aspects of the code changed. This has only happened
infrequently at best (but thanks to those who made the effort)
Most of the time there is absolutely no need for developers to write
any docs at all, there just needs to be some mechanism by which I am
made aware of it. The release notes *are* a lot better, but they don't
cover everything which has changed.

I would be quite happy to use some other system other than HTML5 if:
 1. people would then actually use it
 2. it could deliver the same end-user experience.

This latter point is more of a problem. There is no convention in
markdown etc for things like the foldouts we use in the docs, or the
asides, or the walkthroughs, or... etc. Sure, we can *make*
conventions for those, but then it becomes not-exactly-markdown, and
people who aren't regularly documenting stuff will find that a barrier
too.

Until recently there has been little point in versioning the docs, as
they have been missing so much anyway we would just have had several
incomplete versions. I think we should have versions for 1.16.x and
1.18.x when that is released, and ongoing dev version docs.

So, I do have a proposal. If someone wants to decide what system or
method would actually make documentation happen, I propose that we use
that for the dev versions. When a stable release is made, I will
convert and edit the <in whatever format> docs to nice ones that
people can actually navigate and use.  So, the action point here is:

* Developers to confer and decide what method/tools they wish to use
to generate docs for the dev series. E.g. something like markdown with
https://github.com/assemble/assemble.


Nick