As you find these things, please create an issue in the JIRA.
At least there will be a record of what needs fixing.
The dispersion of effort and information between the docs and the wiki
needs some discussion.
To an outsider, the wiki seems to be a place that is used to compensate
for the deficiencies and errors in the manuals. That just makes it hard
to find the right information.
Ron
On 10/10/2013 3:11 PM, Fred Messinger wrote:
Agreed Carlos. I've spent all day reading said emails and trying to
wrangle through this problem myself. How to update the templates is here:
https://cwiki.apache.org/confluence/display/CLOUDSTACK/How+to+build+CloudStack#
but even getting that to work was an adventure.
On Thu, Oct 10, 2013 at 2:44 PM, Carlos Reategui <car...@reategui.com>wrote:
On Thu, Oct 10, 2013 at 10:48 AM, David Nalley <da...@gnsa.us> wrote:
That is how it has been done previously - but we recently moved docs
to their own repo to separate the software lifecycle from the docs
lifecycle, and we have already had at least one update pushed to the
docs post-release.
Over the past couple weeks a good percentage of the emails to the list have
been caused due to the wrong template URL in the installation docs. I just
had a look and they are still pointing to the old templates.
Along the same lines the other problem most people have had is not knowing
to upgrade the templates when upgrading from 4.1 to 4.2. Just had a look
at the docs and that is still not been updated.
I would have thought this would have been a high priority to fix and would
have been in that first update given the number of people running into
these.
The goal is to try and keep this up, and I hope to
publish another set of updates tomorrow or over the weekend.
Bad docs make even the best software unusable IMO. That said, we could
use more eyeballs - at least identify the problems for us. Bonus
points for fixes.
Can you point us to a guide on how to make doc fixes? Is this in git? I
though I just saw a reference to SVN in another email in this thread.
--David
On Wed, Oct 9, 2013 at 4:24 PM, Carlos Reategui <create...@gmail.com>
wrote:
It seems like the only way that docs (
http://cloudstack.apache.org/docs/en-US/index.html) are updated is
when
a
release is done. Is it not possible to have these updated otherwise?
Waiting for the next patch release of the software so that the docs
get
updated is causing problems with folks not being able to get CloudStack
installed properly and therefore gives them a bad impression of the
maturity of CloudStack.
It makes no sense to me why there are multiple versions of documents
for
each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2,
4.1.0,
4.1.1 and 4.0.2 docs) when the feature set has not changed within each
of
these. I understand that the docs are built as part of the build and
release process but why does that have to impact the rate at which the
primary doc site is updated. Can't the patch releases simply update
the
release notes? Personally I think there should be a single 4.x version
of
the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major
features are going to be added to them). Maybe the doc site should
have
wiki like capabilities so that it can be more easily maintained.
ok, I am done ranting...
--
Ron Wheeler
President
Artifact Software Inc
email: rwhee...@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
