drafts section of the juju docs

[Gustavo Niemeyer]

On Wed, Jun 20, 2012 at 6:12 PM, Mark Mims <mark.mims at canonical.com> wrote:
> Ah, good point... it's a lot of work to map docs against two separate
> projects.  What features described in the docs are implemented in go at any
> given time?  It seems like that problem's solved by keeping the docs with
> the code.

And then have two copies of the documentation? This sounds pretty bad.

> What we've effectively done is overloaded the documentation to include the
> notion of feature approval.  I.e., what does it mean for a feature spec to
> be approved? It means it's been accepted into drafts on docs trunk.  That's
> what leads to potential leakage of spec'd feature docs.  Can we capture
> feature approval somewhere else?  i.e., tags on the feature branch or bug?

Sorry, I really don't understand what problem we have. We have
documentation being reviewed and included into the documentation
branch after it makes sense. That's called "publishing", not
"leaking".

> If we do keep up the current process, we need to please make sure that MPs
> include notes to move docs from drafts to release locations.  If we do this

Agreed, it's quite possible that we haven't done a great job in this area.

> at code merge time, then we just have to deal with the fact that the docs
> will be out of sync with the code until the next ppa build and/or distro
> release, but at least the developers are the ones updating the docs from
> draft status and not ~charm-contributors.

The documentation doesn't have to be out of date with the code, if we
do a better job and include version information pointing out when a
given feature or detail started to make sense ("This was introduced in
version X.Y.Z").

> Generally, we also need to figure out when to release the docs.  ppa build

What's in docs trunk should be published, IMO.


gustavo @ http://niemeyer.net