[DOCS] Questions on doc freeze

[Jessica Tomechak <je...@gmail.com>]

Starting a new thread. There are a lot of questions around when to freeze
docs, and when to publish updated docs. I'll start a separate thread for
the latter.

First, the question of when to freeze docs before a release. Adding an
unreviewed doc the night before release wouldn't be the best practice. Yet
freezing docs a month before the release seems to me too early. We want
something in between, allowing  time for new docs to pass a technical
review *and QA test* where applicable.

What do I mean by QA test? If a doc includes any how-to instructions, a 3rd
party should try to follow the steps to make sure the instructions are
clear and correct. This avoids so many post-release doc bugs like "you
forgot I have to run the setup-something-essential script first", and of
course the ever popular "there was a typo in the command" (everybody just
cut-and-pastes commands).

I am not sure what mechanism we want to use to make sure docs pass any of
these tests/reviews before going out. I'm not sure how strict we want to be
about it, either. But it seems the time is ripe to discuss it.

Jessica T.

Re: [DOCS] Questions on doc freeze

[David Nalley <da...@gnsa.us>]

On Wed, Feb 20, 2013 at 8:51 PM, Jessica Tomechak
<je...@gmail.com> wrote:
> Starting a new thread. There are a lot of questions around when to freeze
> docs, and when to publish updated docs. I'll start a separate thread for
> the latter.
>
> First, the question of when to freeze docs before a release. Adding an
> unreviewed doc the night before release wouldn't be the best practice. Yet
> freezing docs a month before the release seems to me too early. We want
> something in between, allowing  time for new docs to pass a technical
> review *and QA test* where applicable.
>
> What do I mean by QA test? If a doc includes any how-to instructions, a 3rd
> party should try to follow the steps to make sure the instructions are
> clear and correct. This avoids so many post-release doc bugs like "you
> forgot I have to run the setup-something-essential script first", and of
> course the ever popular "there was a typo in the command" (everybody just
> cut-and-pastes commands).
>
> I am not sure what mechanism we want to use to make sure docs pass any of
> these tests/reviews before going out. I'm not sure how strict we want to be
> about it, either. But it seems the time is ripe to discuss it.

So my take on this is a bit different.
First, we discussed the 4.1 release schedule, which included doc
freeze, back in November. (See the first such thread there.
http://cloudstack.markmail.org/thread/usovfra4j5t5ktwn)


Doc freeze is very much like code freeze, but for slightly different reasons.
The big reasons are:
People need to be testing code along side the docs they are using, if
there are still massive changes coming in, it steals the 'QA' eyes
that we could otherwise make use of. If doc freeze doesn't mirror code
freeze, docs can't be used by folks doing QA to do their work.
Second, we have folks working on translating docs, changing large
swaths of documentation after they've started their work wastes their
time, because they needlessly have to repeat it. Also, they just need
time to do the work, and there is lots of work to do. (CloudStack docs
alone have 6720 strings right now to translate.)

We had feature freeze (e.g. all of the new features should have been
present and in the codebase, and working approximately a month before
code freeze, which should handle most of the functionality people need
to document.

Finally - doc freeze isn't absolute, blocker and critical doc bugs,
(just like blocker and critical code bugs) can still be pushed in, up
until release. Thought naturally we want to minimize that if at all
possible because of l10n.

On the 'docs should be QAed before release' note. It would be awesome
if they were, and I'd love to see that. And given the help we recently
received from folks on the users list with the QIG/runbook, I suspect
that folks would gladly jump in and help go through the docs. That
said, just like the code - when we finally cut a release and ship it,
the docs in the repo are the docs for the release.

--David