cloudstack-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ron Wheeler <rwhee...@artifact-software.com>
Subject Re: Doc Updates
Date Fri, 11 Oct 2013 12:38:26 GMT
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 <carlos@reategui.com>wrote:
>
>> On Thu, Oct 10, 2013 at 10:48 AM, David Nalley <david@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 <creategui@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: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102


Mime
View raw message