RE: Documentation issue in CloudStack 4.1

[Radhika Puthiyetath <ra...@citrix.com>]

+ Dev list.

+1 

We should have someone to sign off each section before the release.

-----Original Message-----
From: Ron Wheeler [mailto:rwheeler@artifact-software.com] 
Sent: Monday, August 19, 2013 7:03 PM
To: users@cloudstack.apache.org
Subject: Re: Documentation issue in CloudStack 4.1

It is too bad that an errata list can not be applied to an existing release in the same way that a book publisher issues one against a printed book.

Suggestion:
Docs should be tested in the same way that the code is.

At least try the installation once to see if it still works.
I hope that 4.2 will actually work as described.

Have someone read each section once and sign off on it before the release decision is made.

Get rid of the duplication between external documentation wikis and the manuals.
There is not enough manpower to maintain both and having 3 places to look for documentation is just confusing.

The wikis are easy to maintain but hard to version.

Ron


On 19/08/2013 5:05 AM, Sebastien Goasguen wrote:
> On Aug 19, 2013, at 4:50 AM, Ryan Lei <ry...@cht.com.tw> wrote:
>
>> More specifically, Ashutosh, did you forget to use baseurl= 
>> http://cloudstack.apt-get.eu/rhel/4.1/ in your yum setting?
>> Ironically, the 4.1.0 Installation Guide still points to 4.0, whose 
>> doc fix can only be applied to the next version 4.1.1.
>>
>> It's sad to me that critical doc mistakes like this will stay in the 
>> 4.1.0 docs "forever", just as the 4.0.2 Release Note would always 
>> have the title 4.0.1-incubating even if there was 4.0.3 (It was fixed 
>> in the 4.0 branch, though [1]). These fixes just can't be backported to docs already "online."
>> (sigh)
> Well, the error you mention is indeed in the 4.1.0 release docs, but 
> it was fixed in subsequent release 4.1.1
>   
> Everyone should aim to install the latest version: if 4.1.1 is out then try to avoid installing 4.1.0 and don't read the 4.1.0 docs.
>
> But I understand what you are saying and we definitely need everyone to file bugs for docs defects, we need to fix them and improve the docs greatly.
>
> Any help/recommendations much welcome !
>
> -sebastien
>
>
>> [1] https://issues.apache.org/jira/browse/CLOUDSTACK-2204
>>
>> ---------------------------------------------------------------------
>> ---------------------- Yu-Heng (Ryan) Lei, Associate Researcher 
>> Chunghwa Telecom Laboratories / Cloud Computing Laboratory 
>> ryanlei@cht.com.tw<https://email.cht.com.tw/owa/redir.aspx?C=-wE1FEC3
>> G0SWYpVkiWo8SsDdf3ZqO9AIuAPTzRnFYCUi-z4YljtI_hyVKkNHfn9F1Bn-vUWJnQ4.&
>> URL=mailto%3aryanlei%40cht.com.tw>
>> or
>> ryanlei750328@gmail.com
>>
>>
>>
>> On Mon, Aug 19, 2013 at 4:33 PM, Sebastien Goasguen <ru...@gmail.com>wrote:
>>
>>> On Aug 19, 2013, at 4:29 AM, Ryan Lei <ry...@cht.com.tw> wrote:
>>>
>>>> That's weird. My environment has the community RPMs [1] installed 
>>>> (tried both 4.1.0 and 4.1.1), but there DOES exist the
>>> cloudstack-setup-databases
>>>> command, located in /usr/bin.
>>>>
>>>> $ which cloudstack-setup-databases
>>>> /usr/bin/cloudstack-setup-databases
>>>>
>>>> As I remember, these cloud-*** commands have all changed their 
>>>> titles to
>>>> cloudstack-*** since version 4.1. So I was confused when I first 
>>>> read
>>> your
>>>> thread concerning 4.1.
>>>>
>>>> Are you using a RPM-based Linux and the community RPMs, too? I have 
>>>> no
>>> idea
>>>> why you have cloud-setup-databases, instead!
>>>>
>>>> [1] http://cloudstack.apt-get.eu/rhel/4.1/
>>>
>>> Ryan, I actually agree with you and I remember fixing the doc for this.
>>>
>>> Ashutosh, are you using 4.0 instead of 4.1 ?
>>>
>>>>
>>> --------------------------------------------------------------------
>>> -----------------------
>>>> Yu-Heng (Ryan) Lei, Associate Reasearcher Chunghwa Telecom 
>>>> Laboratories / Cloud Computing Laboratory ryanlei@cht.com.tw<
>>> https://email.cht.com.tw/owa/redir.aspx?C=-wE1FEC3G0SWYpVkiWo8SsDdf3
>>> ZqO9AIuAPTzRnFYCUi-z4YljtI_hyVKkNHfn9F1Bn-vUWJnQ4.&URL=mailto%3aryan
>>> lei%40cht.com.tw
>>>> or
>>>> ryanlei750328@gmail.com
>>>>
>>>>
>>>>
>>>> On Fri, Jul 12, 2013 at 6:01 PM, Ashutosh Narayan < 
>>>> aashutoshnarayan@gmail.com> wrote:
>>>>
>>>>> Hi Folks,
>>>>>
>>>>> I just came across some command issues in the installation 
>>>>> document mentioned on this link -
>>>>>
>>>>>
>>> http://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.1.0/html
>>> /Installation_Guide/management-server-install-flow.html
>>>>> Section 4.5.4.1 has *cloudstack-setup-databases* but no such 
>>>>> command is found instead *cloud-setup-databases* is present for 
>>>>> CloudStack version 4.1. Looks like a documentation issue.
>>>>>
>>>>> Just wanted the list to know.
>>>>>
>>>>> Thank you,
>>>>> --
>>>>> Ashutosh Narayan
>>>>>
>>>>> http://ashutoshn.wordpress.com/
>>>>>
>>>
>


--
Ron Wheeler
President
Artifact Software Inc
email: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102