You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by Jessica Tomechak <je...@gmail.com> on 2013/02/21 02:49:31 UTC
[DOCS] Questions on publishing and updating documentation
There's a question of how to publish docs, and how often to update docs for
previous releases, if at all.
Publishing new docs:
As far as I know, docs aren't auto-uploaded to the doc site [1] every time
a new doc build results in new output. I think there's a manual upload, and
I don't know whether it's documented. I wish that I had the steps and
permissions, because I would like to be able to push doc fixes when it's
appropriate. At the least, more than one person should have the know-how.
If some subset of people are already "maintainers" on this process, let's
add that info somewhere in the Doc Writers part of the project wiki.[2]
Updating old docs:
My practice with CloudStack docs pre-Apache was always to propagate fixes
backwards to whatever releases they affected, put a new "Updated On:" date
on the title page, and republish. I don't know whether we want to be that
exhaustive about backwards-maintaining published docs. It's possible we
want to do this only for real "showstopper" errors in the docs...like, say,
incorrect installation instructions or security holes. Or maybe we do want
true real-time updates to all docs in all versions.
So far in the life of ACS, it seems we have frozen the docs for release
4.0.0 and have not updated them since they were first posted on
http://incubator.apache.org/cloudstack/docs/. (I am not sure, because I
don't see an Updated: timestamp.) If any doc bug-fixes have been checked in
to a 4.0.0 branch since then, it would be great to rebuild and upload those
docs again.
It does not appear we published updated docs for 4.0.1. So that brings up
another question. Do we want to update docs for every minor release? Or
just for moves like 4.0 to 4.1?
[1] http://incubator.apache.org/cloudstack/docs
[2]
https://cwiki.apache.org/confluence/display/CLOUDSTACK/Documentation+Team
Jessica T.
Re: [DOCS] Questions on publishing and updating documentation
Posted by David Nalley <da...@gnsa.us>.
On Fri, Feb 22, 2013 at 8:29 PM, Jessica Tomechak
<je...@gmail.com> wrote:
> On Wed, Feb 20, 2013 at 8:29 PM, David Nalley <da...@gnsa.us> wrote:
>
>> So I've written some inline responses to this message - but when I got
>> to the bottom, I realized that the disconnect here is likely caused by
>> the differences in how releases and more importantly, git branches are
>> handled here. So, hopefully this will explain it.
>>
>> For each feature release (4.1, 4.2, 4.3, etc) there is a release
>> branch. This branch is created at feature freeze for that feature
>> release. At that point, the code will never have any more features. We
>> begin bugfixes, QA, docs, etc on that release. When we cut a release,
>> we don't branch, but instead, tag the version (which essentially is a
>> bookmark in the git repos timeline of commits) work continues in the
>> release branch for the next bugfix release (i.e. 4.0.2 that's going on
>> right now) and each of those bugfix releases is a tag from the release
>> branch.
>>
>> This is pretty different than the way release branches were handled
>> pre-ASF. In that case we had main version branch (AKA 3.0.x), and each
>> point release had it's own branch as well (i.e. 3.0.2) This meant you
>> could 'patch' things in 3.0.2 if you needed a specific bugfix. For all
>> practical purposes you can't do that here. (well you technically can,
>> but lets just say it's messy and bad form to do so, and lots of extra
>> work)
>>
>> On Wed, Feb 20, 2013 at 8:49 PM, Jessica Tomechak
>> <je...@gmail.com> wrote:
>> > There's a question of how to publish docs, and how often to update docs
>> for
>> > previous releases, if at all.
>> >
>> > Publishing new docs:
>> > As far as I know, docs aren't auto-uploaded to the doc site [1] every
>> time
>> > a new doc build results in new output. I think there's a manual upload,
>> and
>>
>> That is correct. There is no autoupdate. Reasoning for this below.
>>
>> > I don't know whether it's documented. I wish that I had the steps and
>> > permissions, because I would like to be able to push doc fixes when it's
>> > appropriate. At the least, more than one person should have the know-how.
>> > If some subset of people are already "maintainers" on this process, let's
>> > add that info somewhere in the Doc Writers part of the project wiki.[2]
>> >
>>
>> I think several folks have the knowledge. Joe and I worked through
>> this one day on IRC and he has the logs, not sure whether he's
>> transitioned that to wiki documentation or not.
>>
>>
>>
>> > Updating old docs:
>> > My practice with CloudStack docs pre-Apache was always to propagate fixes
>> > backwards to whatever releases they affected, put a new "Updated On:"
>> date
>> > on the title page, and republish. I don't know whether we want to be that
>> > exhaustive about backwards-maintaining published docs. It's possible we
>> > want to do this only for real "showstopper" errors in the docs...like,
>> say,
>> > incorrect installation instructions or security holes. Or maybe we do
>> want
>> > true real-time updates to all docs in all versions.
>> >
>>
>> Well 'real time' causes other problems. For instance - if you update
>> something, is that update valid for the version that being updated?
>> (it's technically version+1 in the codebase, so where does that update
>> apply, version already released, or version +1?)
>>
>> We also have to remember that we have a growing l10n community, our
>> various content pieces are being translated into ~14 different
>> languages. Every change we make means those fall out of sync, and we
>> have to know two things to be able to go back in time and update:
>> 1) At what point in time (commit reference) were those documents
>> generated? (we need to be able to generate pots, potentially
>> regenerate the site, etc)
>> 2) If I begin updating from that reference, what's the impact?
>>
>> Let me explain the problem.
>> We currently have 4.0.0 and 4.0.1 - they both began life in the 4.0
>> release branch. If you made an update to docs, and push it out - are
>> we sure it applies to both 4.0.0 and 4.0.1? (It should, except in the
>> case of release notes) Now, suppose I want to translate the docs, how
>> do I know what point in time the published docs are from? How do I get
>> that translation incorporated and docs built? (the short answer is
>> some nasty branching, that I'd really prefer not to do, but it is
>> technically possible, just ill-advised).
>>
>> For this (and several other) reason, the code and docs at freeze are
>> the released documentation. Because we have relatively rapid bugfix
>> releases, it's pretty easy to release bugfixes to docs as well when
>> those happen (which was very much the case in the 4.0.1 release.)
>
>
>>
>> > So far in the life of ACS, it seems we have frozen the docs for release
>> > 4.0.0 and have not updated them since they were first posted on
>> > http://incubator.apache.org/cloudstack/docs/. (I am not sure, because I
>> > don't see an Updated: timestamp.) If any doc bug-fixes have been checked
>> in
>> > to a 4.0.0 branch since then, it would be great to rebuild and upload
>> those
>> > docs again.
>> >
>>
>> So a couple of clarifications. There is no 4.0.0-incubating branch -
>> there is only a 4.0.0-incubating tag. The tag is a point in time of
>> the 4.0 branch. (We handle branching and releases significantly
>> differently than we used to pre-ASF, there is much more rigor here to
>> the release philosophy) Because it's a tag and not a branch, there is
>> no way to check into 4.0.0, just the update stream for 4.0 (which is
>> more akin to the 3.0.x branch pre-ASF)
>>
>>
>> > It does not appear we published updated docs for 4.0.1. So that brings up
>> > another question. Do we want to update docs for every minor release? Or
>> > just for moves like 4.0 to 4.1?
>> >
>>
>> We did publish for 4.0.1 - the day it released, from what was tagged as
>> 4.0.1.
>>
>
> I don't see any updated docs marked "4.0.1" on the doc website. Can you say
> a bit more about this, please? Are we publishing somewhere else now? I am
> looking at:
>
> http://incubator.apache.org/cloudstack/docs/
Browser cache?
http://incubator.apache.org/cloudstack/docs/en-US/Apache_CloudStack/4.0.1-incubating/html/Release_Notes/index.html
http://incubator.apache.org/cloudstack/docs/en-US/Apache_CloudStack/4.0.1-incubating/html/Installation_Guide/index.html
http://incubator.apache.org/cloudstack/docs/en-US/Apache_CloudStack/4.0.1-incubating/html/Admin_Guide/index.html
http://incubator.apache.org/cloudstack/docs/en-US/Apache_CloudStack/4.0.1-incubating/html/API_Developers_Guide/index.html
>
> To your more general comments: If it's technically difficult and/or
> philosophically undesirable to update older docs on the website, and that's
> the community's consensus, fine. It certainly makes life easier, and makes
> better translation possible, as you noted. So docs would be "set in stone"
> once they're uploaded to the site?
Docs set in stone at release, I'd surmise.
>
> Would we make any exceptions? Say there are really stupid command errors
> that make it impossible to install the software, or "Best Practices" that
> turn out to cause huge security holes. Or would we rather just handle those
> with addendums, release notes, and blog posts?
>
I am sure that some room for exceptions would exist, but no thoughts
to pre-defining them.
--David
Re: [DOCS] Questions on publishing and updating documentation
Posted by Jessica Tomechak <je...@gmail.com>.
On Wed, Feb 20, 2013 at 8:29 PM, David Nalley <da...@gnsa.us> wrote:
> So I've written some inline responses to this message - but when I got
> to the bottom, I realized that the disconnect here is likely caused by
> the differences in how releases and more importantly, git branches are
> handled here. So, hopefully this will explain it.
>
> For each feature release (4.1, 4.2, 4.3, etc) there is a release
> branch. This branch is created at feature freeze for that feature
> release. At that point, the code will never have any more features. We
> begin bugfixes, QA, docs, etc on that release. When we cut a release,
> we don't branch, but instead, tag the version (which essentially is a
> bookmark in the git repos timeline of commits) work continues in the
> release branch for the next bugfix release (i.e. 4.0.2 that's going on
> right now) and each of those bugfix releases is a tag from the release
> branch.
>
> This is pretty different than the way release branches were handled
> pre-ASF. In that case we had main version branch (AKA 3.0.x), and each
> point release had it's own branch as well (i.e. 3.0.2) This meant you
> could 'patch' things in 3.0.2 if you needed a specific bugfix. For all
> practical purposes you can't do that here. (well you technically can,
> but lets just say it's messy and bad form to do so, and lots of extra
> work)
>
> On Wed, Feb 20, 2013 at 8:49 PM, Jessica Tomechak
> <je...@gmail.com> wrote:
> > There's a question of how to publish docs, and how often to update docs
> for
> > previous releases, if at all.
> >
> > Publishing new docs:
> > As far as I know, docs aren't auto-uploaded to the doc site [1] every
> time
> > a new doc build results in new output. I think there's a manual upload,
> and
>
> That is correct. There is no autoupdate. Reasoning for this below.
>
> > I don't know whether it's documented. I wish that I had the steps and
> > permissions, because I would like to be able to push doc fixes when it's
> > appropriate. At the least, more than one person should have the know-how.
> > If some subset of people are already "maintainers" on this process, let's
> > add that info somewhere in the Doc Writers part of the project wiki.[2]
> >
>
> I think several folks have the knowledge. Joe and I worked through
> this one day on IRC and he has the logs, not sure whether he's
> transitioned that to wiki documentation or not.
>
>
>
> > Updating old docs:
> > My practice with CloudStack docs pre-Apache was always to propagate fixes
> > backwards to whatever releases they affected, put a new "Updated On:"
> date
> > on the title page, and republish. I don't know whether we want to be that
> > exhaustive about backwards-maintaining published docs. It's possible we
> > want to do this only for real "showstopper" errors in the docs...like,
> say,
> > incorrect installation instructions or security holes. Or maybe we do
> want
> > true real-time updates to all docs in all versions.
> >
>
> Well 'real time' causes other problems. For instance - if you update
> something, is that update valid for the version that being updated?
> (it's technically version+1 in the codebase, so where does that update
> apply, version already released, or version +1?)
>
> We also have to remember that we have a growing l10n community, our
> various content pieces are being translated into ~14 different
> languages. Every change we make means those fall out of sync, and we
> have to know two things to be able to go back in time and update:
> 1) At what point in time (commit reference) were those documents
> generated? (we need to be able to generate pots, potentially
> regenerate the site, etc)
> 2) If I begin updating from that reference, what's the impact?
>
> Let me explain the problem.
> We currently have 4.0.0 and 4.0.1 - they both began life in the 4.0
> release branch. If you made an update to docs, and push it out - are
> we sure it applies to both 4.0.0 and 4.0.1? (It should, except in the
> case of release notes) Now, suppose I want to translate the docs, how
> do I know what point in time the published docs are from? How do I get
> that translation incorporated and docs built? (the short answer is
> some nasty branching, that I'd really prefer not to do, but it is
> technically possible, just ill-advised).
>
> For this (and several other) reason, the code and docs at freeze are
> the released documentation. Because we have relatively rapid bugfix
> releases, it's pretty easy to release bugfixes to docs as well when
> those happen (which was very much the case in the 4.0.1 release.)
>
> > So far in the life of ACS, it seems we have frozen the docs for release
> > 4.0.0 and have not updated them since they were first posted on
> > http://incubator.apache.org/cloudstack/docs/. (I am not sure, because I
> > don't see an Updated: timestamp.) If any doc bug-fixes have been checked
> in
> > to a 4.0.0 branch since then, it would be great to rebuild and upload
> those
> > docs again.
> >
>
> So a couple of clarifications. There is no 4.0.0-incubating branch -
> there is only a 4.0.0-incubating tag. The tag is a point in time of
> the 4.0 branch. (We handle branching and releases significantly
> differently than we used to pre-ASF, there is much more rigor here to
> the release philosophy) Because it's a tag and not a branch, there is
> no way to check into 4.0.0, just the update stream for 4.0 (which is
> more akin to the 3.0.x branch pre-ASF)
>
>
> > It does not appear we published updated docs for 4.0.1. So that brings up
> > another question. Do we want to update docs for every minor release? Or
> > just for moves like 4.0 to 4.1?
> >
>
> We did publish for 4.0.1 - the day it released, from what was tagged as
> 4.0.1.
>
I don't see any updated docs marked "4.0.1" on the doc website. Can you say
a bit more about this, please? Are we publishing somewhere else now? I am
looking at:
http://incubator.apache.org/cloudstack/docs/
To your more general comments: If it's technically difficult and/or
philosophically undesirable to update older docs on the website, and that's
the community's consensus, fine. It certainly makes life easier, and makes
better translation possible, as you noted. So docs would be "set in stone"
once they're uploaded to the site?
Would we make any exceptions? Say there are really stupid command errors
that make it impossible to install the software, or "Best Practices" that
turn out to cause huge security holes. Or would we rather just handle those
with addendums, release notes, and blog posts?
Thanks,
Jessica T.
Re: [DOCS] Questions on publishing and updating documentation
Posted by David Nalley <da...@gnsa.us>.
So I've written some inline responses to this message - but when I got
to the bottom, I realized that the disconnect here is likely caused by
the differences in how releases and more importantly, git branches are
handled here. So, hopefully this will explain it.
For each feature release (4.1, 4.2, 4.3, etc) there is a release
branch. This branch is created at feature freeze for that feature
release. At that point, the code will never have any more features. We
begin bugfixes, QA, docs, etc on that release. When we cut a release,
we don't branch, but instead, tag the version (which essentially is a
bookmark in the git repos timeline of commits) work continues in the
release branch for the next bugfix release (i.e. 4.0.2 that's going on
right now) and each of those bugfix releases is a tag from the release
branch.
This is pretty different than the way release branches were handled
pre-ASF. In that case we had main version branch (AKA 3.0.x), and each
point release had it's own branch as well (i.e. 3.0.2) This meant you
could 'patch' things in 3.0.2 if you needed a specific bugfix. For all
practical purposes you can't do that here. (well you technically can,
but lets just say it's messy and bad form to do so, and lots of extra
work)
On Wed, Feb 20, 2013 at 8:49 PM, Jessica Tomechak
<je...@gmail.com> wrote:
> There's a question of how to publish docs, and how often to update docs for
> previous releases, if at all.
>
> Publishing new docs:
> As far as I know, docs aren't auto-uploaded to the doc site [1] every time
> a new doc build results in new output. I think there's a manual upload, and
That is correct. There is no autoupdate. Reasoning for this below.
> I don't know whether it's documented. I wish that I had the steps and
> permissions, because I would like to be able to push doc fixes when it's
> appropriate. At the least, more than one person should have the know-how.
> If some subset of people are already "maintainers" on this process, let's
> add that info somewhere in the Doc Writers part of the project wiki.[2]
>
I think several folks have the knowledge. Joe and I worked through
this one day on IRC and he has the logs, not sure whether he's
transitioned that to wiki documentation or not.
> Updating old docs:
> My practice with CloudStack docs pre-Apache was always to propagate fixes
> backwards to whatever releases they affected, put a new "Updated On:" date
> on the title page, and republish. I don't know whether we want to be that
> exhaustive about backwards-maintaining published docs. It's possible we
> want to do this only for real "showstopper" errors in the docs...like, say,
> incorrect installation instructions or security holes. Or maybe we do want
> true real-time updates to all docs in all versions.
>
Well 'real time' causes other problems. For instance - if you update
something, is that update valid for the version that being updated?
(it's technically version+1 in the codebase, so where does that update
apply, version already released, or version +1?)
We also have to remember that we have a growing l10n community, our
various content pieces are being translated into ~14 different
languages. Every change we make means those fall out of sync, and we
have to know two things to be able to go back in time and update:
1) At what point in time (commit reference) were those documents
generated? (we need to be able to generate pots, potentially
regenerate the site, etc)
2) If I begin updating from that reference, what's the impact?
Let me explain the problem.
We currently have 4.0.0 and 4.0.1 - they both began life in the 4.0
release branch. If you made an update to docs, and push it out - are
we sure it applies to both 4.0.0 and 4.0.1? (It should, except in the
case of release notes) Now, suppose I want to translate the docs, how
do I know what point in time the published docs are from? How do I get
that translation incorporated and docs built? (the short answer is
some nasty branching, that I'd really prefer not to do, but it is
technically possible, just ill-advised).
For this (and several other) reason, the code and docs at freeze are
the released documentation. Because we have relatively rapid bugfix
releases, it's pretty easy to release bugfixes to docs as well when
those happen (which was very much the case in the 4.0.1 release.)
> So far in the life of ACS, it seems we have frozen the docs for release
> 4.0.0 and have not updated them since they were first posted on
> http://incubator.apache.org/cloudstack/docs/. (I am not sure, because I
> don't see an Updated: timestamp.) If any doc bug-fixes have been checked in
> to a 4.0.0 branch since then, it would be great to rebuild and upload those
> docs again.
>
So a couple of clarifications. There is no 4.0.0-incubating branch -
there is only a 4.0.0-incubating tag. The tag is a point in time of
the 4.0 branch. (We handle branching and releases significantly
differently than we used to pre-ASF, there is much more rigor here to
the release philosophy) Because it's a tag and not a branch, there is
no way to check into 4.0.0, just the update stream for 4.0 (which is
more akin to the 3.0.x branch pre-ASF)
> It does not appear we published updated docs for 4.0.1. So that brings up
> another question. Do we want to update docs for every minor release? Or
> just for moves like 4.0 to 4.1?
>
We did publish for 4.0.1 - the day it released, from what was tagged as 4.0.1.