You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by Dag Sonstebo <Da...@shapeblue.com> on 2016/05/19 10:54:35 UTC
[Discuss] CloudStack documentation
All,
since we've added CloudStack documentation to the discussion topics for the Montreal meetup I wanted to gauge peoples opinion on areas of improvement.
Personally I would like to see the following:
1. Overall documentation navigation needs to be improved.
2. Ideally all documentation should be under a single documentation tree with a single table of contents. All content should be searchable without having to visit each of the current documentation roots separately (Getting Started / Installation Guide / Admin Guide / Release Notes).
3. Advanced topics should be moved away from the "Getting Started Docs". The people reading the getting started / concepts sections are typically new CloudStack users who will easily be put off by immediately being presented with advanced topics.
4. API documentation to be a chapter of the Developers guide.
5. Upgrade instructions to be moved from the release notes to the installation guide.
6. Compatibility matrix in single location only – i.e. not in both the release notes and installation guide as this has caused discrepancies in the past.
I appreciate we are also working against multiple Github repositories which complicates things slightly, but if we can overall improve the end user experience this is worth the effort.
Thoughts?
Regards,
Dag.Sonstebo@shapeblue.com
www.shapeblue.com
53 Chandos Place, Covent Garden, London WC2N 4HSUK
@shapeblue
Re: [Discuss] CloudStack documentation
Posted by Ron Wheeler <rw...@artifact-software.com>.
A couple of comments.
The definition of the audience for each document should be clearly
understood.
Size: What is targeted for large organizations (hundreds of servers)
with dedicated staff and sophisticated needs - what is targeted for SMB
(5-50 servers) with limited staff and simple needs. Where are new user
organizations coming from
Knowledge required - How to organize and present information in a way
that is accessible by dedicated specialists while making it easy for
system administrators with limited time and less specialized knowledge
to get what they need.
I may not understand the reStructured Text philosophy but it seems to be
very difficult to reuse topics and very hard to use any of the
documentation to build a custom manual for an installation. It seems to
be hard to avoid having the same idea expressed in multiple places with
contradictory terminology and sometime contradictory factual statements.
The monolithic nature of the topics makes it hard to follow the flow of
the documents and hard to share the editing tasks.
I have been using DITA and it seems like a better way to produce and
maintain documentation in that it encourages reuse rather than copy and
paste and breaks the documents into smaller more focused chunks that can
be maintained by edits that affect only a small fragment of text rather
than having to search through a large documents to find the places
requiring changes.
I will be attending the conference and will be providing a living
example of someone with almost no practical experience with Cloudstack
which I hope will balance out the great depth of the other participants
when it come to reviewing documentation for readability and clarity.
Ron
On 20/05/2016 10:43 AM, Rajsekhar K wrote:
> Hi, All,
>
> I agree with Dag Sonstebo that we need to improve the layout and navigation of CloudStack documentation. I think that the improvement should begin from the home page.
>
> New users may not find the way the information presented on the home page very intuitive. A few tweaking on the home page will help us improve the information experience of CloudStack users.
>
> Here are my thoughts on improving CloudStack documentation:
>
> \u2022 Our users - mostly experienced administrators- would install CloudStack and understand the basic concepts, deployment architecture, and terminologies first. After doing this, they would be delighted to see the big picture of the tasks that they can do with CloudStack.
>
> So, a home page for CloudStack documentation that displays the big picture of the tasks that the users can do with CloudStack will be appreciated. We can display the big picture of the tasks in distinct content blocks on the Home page. Each block will have a link to the documentation and a brief description of the major task. Users will click the link to the documentation to land on the page for that major task. They can, now, see the ToC for the major ask. This ToC will delineate the flow of minor (sub) tasks that constitute the major task.
>
> \u2022 It is useful if we can incorporate videos and lectures on the Home page. Professionally made videos will be very helpful to the users.
>
> \u2022 I think we need to think beyond 'guides' (such as Installation Guide, Administration Guide, and so on) when we present the information online. CloudStack users would be delighted to see a topic that directly answers the question in their mind (such as 'Configuring a XenServer host with CloudStack') than logically locating a help topic by navigating to a guide first, then to a section in the guide and then locating the information. They would be able to access and read the documentation in non-linear manner.
>
> \u2022 Let's ensure that the information on upgrading CloudStack is available distinctly on the Home page. This will help avoid directing the users, who want to upgrade to the next CloudStack version, to the Installation section. Installation section can cater to the users who want to install CloudStack in their environment.
>
> \u2022 I think the home page should highlight the link to API reference pages. Also, I feel that we must improve CloudStack API reference pages by incorporating more useful information to each page.
> Based on the discussions that we had in the community sometime back, I have created a specification document and a template for API references at: https://cwiki.apache.org/confluence/display/CLOUDSTACK/Improving+CloudStack+API+References+-+Specifications
>
> \u2022 We can consolidate all matrixes at one location. Along with compatibility matrix, we need to identify information that we can present as matrix. The users should be able to access all these information from the documentation home page.
>
> \u2022 I would like to mention the effort that we have started on creating a reference book for the CloudStack configuration parameters. I hope, this will enhance the information experience of CloudStack users by educating them about the parameters that they can use for configuring CloudStack. I have published some initial information in the following cwiki pages and am awaiting thoughts/reviews from the community members:
> o Apache CloudStack Configuration Parameters Reference Guide - Tasks and Status - https://cwiki.apache.org/confluence/display/CLOUDSTACK/Apache+CloudStack+Configuration+Parameters+Reference+Guide+-+Tasks+and+Status
> o Configuration Parameters in Apache CloudStack - Categorization - https://cwiki.apache.org/confluence/display/CLOUDSTACK/Configuration+Parameters+in+Apache+CloudStack+-+Categorization
> o direct.agent.load.size (sample topic) - https://cwiki.apache.org/confluence/display/CLOUDSTACK/direct.agent.load.size
>
> Also, I think it is a good idea to educate the contributors about creating/updating the CloudStack documentation using reStructured Text. I am facing an issue on this. I want to update some information in the Install Guide, but I could not find guidelines on locating the correct files that I need to update. Clear instruction on this will be helpful.
>
> I will discuss these points with my colleague Sowmya Krishnan, who will be attending the CloudStack conference at Montreal.
>
> Regards,
> Rajsekhar K
> Senior Product Engineer | Accelerite, Bangalore
> Email: rajsekhar.k@accelerite.com<ma...@accelerite.com>
>
> -----Original Message-----
> From: Ron Wheeler [mailto:rwheeler@artifact-software.com]
> Sent: Thursday, May 19, 2016 6:17 PM
> To: dev@cloudstack.apache.org
> Subject: Re: [Discuss] CloudStack documentation
>
> Identify where most issues are raised in the ML and fix the docs to reduce the confusion.
> I suspect that Networking is the source of most problems but perhaps other have a better sense of this.
>
> Ron
>
> On 19/05/2016 8:29 AM, Ron Wheeler wrote:
>> Removal of duplicate information as part of item 2 . Item 5 has this
>> implicitly.
>>
>> Item 3 +1
>>
>> "Marketing" information targeted at SMB market.
>>
>> Ron
>>
>> On 19/05/2016 6:54 AM, Dag Sonstebo wrote:
>>> All,
>>>
>>> since we've added CloudStack documentation to the discussion topics
>>> for the Montreal meetup I wanted to gauge peoples opinion on areas of
>>> improvement.
>>>
>>> Personally I would like to see the following:
>>>
>>> 1. Overall documentation navigation needs to be improved.
>>> 2. Ideally all documentation should be under a single
>>> documentation tree with a single table of contents. All content
>>> should be searchable without having to visit each of the current
>>> documentation roots separately (Getting Started / Installation Guide
>>> / Admin Guide / Release Notes).
>>> 3. Advanced topics should be moved away from the "Getting Started
>>> Docs". The people reading the getting started / concepts sections are
>>> typically new CloudStack users who will easily be put off by
>>> immediately being presented with advanced topics.
>>> 4. API documentation to be a chapter of the Developers guide.
>>> 5. Upgrade instructions to be moved from the release notes to the
>>> installation guide.
>>> 6. Compatibility matrix in single location only \u2013 i.e. not in
>>> both the release notes and installation guide as this has caused
>>> discrepancies in the past.
>>>
>>> I appreciate we are also working against multiple Github repositories
>>> which complicates things slightly, but if we can overall improve the
>>> end user experience this is worth the effort.
>>>
>>> Thoughts?
>>>
>>> Regards,
>>>
>>> Dag.Sonstebo@shapeblue.com<ma...@shapeblue.com>
>>> www.shapeblue.com<http://www.shapeblue.com>
>>> 53 Chandos Place, Covent Garden, London WC2N 4HSUK @shapeblue
>>>
>>>
>>
>
> --
> Ron Wheeler
> President
> Artifact Software Inc
> email: rwheeler@artifact-software.com<ma...@artifact-software.com>
> skype: ronaldmwheeler
> phone: 866-970-2435, ext 102
>
>
>
>
>
> DISCLAIMER
> ==========
> This e-mail may contain privileged and confidential information which is the property of Accelerite, a Persistent Systems business. It is intended only for the use of the individual or entity to which it is addressed. If you are not the intended recipient, you are not authorized to read, retain, copy, print, distribute or use this message. If you have received this communication in error, please notify the sender and delete all copies of this message. Accelerite, a Persistent Systems business does not accept any liability for virus infected mails.
--
Ron Wheeler
President
Artifact Software Inc
email: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
RE: [Discuss] CloudStack documentation
Posted by Rajsekhar K <ra...@accelerite.com>.
Hi, All,
I agree with Dag Sonstebo that we need to improve the layout and navigation of CloudStack documentation. I think that the improvement should begin from the home page.
New users may not find the way the information presented on the home page very intuitive. A few tweaking on the home page will help us improve the information experience of CloudStack users.
Here are my thoughts on improving CloudStack documentation:
• Our users - mostly experienced administrators- would install CloudStack and understand the basic concepts, deployment architecture, and terminologies first. After doing this, they would be delighted to see the big picture of the tasks that they can do with CloudStack.
So, a home page for CloudStack documentation that displays the big picture of the tasks that the users can do with CloudStack will be appreciated. We can display the big picture of the tasks in distinct content blocks on the Home page. Each block will have a link to the documentation and a brief description of the major task. Users will click the link to the documentation to land on the page for that major task. They can, now, see the ToC for the major ask. This ToC will delineate the flow of minor (sub) tasks that constitute the major task.
• It is useful if we can incorporate videos and lectures on the Home page. Professionally made videos will be very helpful to the users.
• I think we need to think beyond 'guides' (such as Installation Guide, Administration Guide, and so on) when we present the information online. CloudStack users would be delighted to see a topic that directly answers the question in their mind (such as 'Configuring a XenServer host with CloudStack') than logically locating a help topic by navigating to a guide first, then to a section in the guide and then locating the information. They would be able to access and read the documentation in non-linear manner.
• Let's ensure that the information on upgrading CloudStack is available distinctly on the Home page. This will help avoid directing the users, who want to upgrade to the next CloudStack version, to the Installation section. Installation section can cater to the users who want to install CloudStack in their environment.
• I think the home page should highlight the link to API reference pages. Also, I feel that we must improve CloudStack API reference pages by incorporating more useful information to each page.
Based on the discussions that we had in the community sometime back, I have created a specification document and a template for API references at: https://cwiki.apache.org/confluence/display/CLOUDSTACK/Improving+CloudStack+API+References+-+Specifications
• We can consolidate all matrixes at one location. Along with compatibility matrix, we need to identify information that we can present as matrix. The users should be able to access all these information from the documentation home page.
• I would like to mention the effort that we have started on creating a reference book for the CloudStack configuration parameters. I hope, this will enhance the information experience of CloudStack users by educating them about the parameters that they can use for configuring CloudStack. I have published some initial information in the following cwiki pages and am awaiting thoughts/reviews from the community members:
o Apache CloudStack Configuration Parameters Reference Guide - Tasks and Status - https://cwiki.apache.org/confluence/display/CLOUDSTACK/Apache+CloudStack+Configuration+Parameters+Reference+Guide+-+Tasks+and+Status
o Configuration Parameters in Apache CloudStack - Categorization - https://cwiki.apache.org/confluence/display/CLOUDSTACK/Configuration+Parameters+in+Apache+CloudStack+-+Categorization
o direct.agent.load.size (sample topic) - https://cwiki.apache.org/confluence/display/CLOUDSTACK/direct.agent.load.size
Also, I think it is a good idea to educate the contributors about creating/updating the CloudStack documentation using reStructured Text. I am facing an issue on this. I want to update some information in the Install Guide, but I could not find guidelines on locating the correct files that I need to update. Clear instruction on this will be helpful.
I will discuss these points with my colleague Sowmya Krishnan, who will be attending the CloudStack conference at Montreal.
Regards,
Rajsekhar K
Senior Product Engineer | Accelerite, Bangalore
Email: rajsekhar.k@accelerite.com<ma...@accelerite.com>
-----Original Message-----
From: Ron Wheeler [mailto:rwheeler@artifact-software.com]
Sent: Thursday, May 19, 2016 6:17 PM
To: dev@cloudstack.apache.org
Subject: Re: [Discuss] CloudStack documentation
Identify where most issues are raised in the ML and fix the docs to reduce the confusion.
I suspect that Networking is the source of most problems but perhaps other have a better sense of this.
Ron
On 19/05/2016 8:29 AM, Ron Wheeler wrote:
> Removal of duplicate information as part of item 2 . Item 5 has this
> implicitly.
>
> Item 3 +1
>
> "Marketing" information targeted at SMB market.
>
> Ron
>
> On 19/05/2016 6:54 AM, Dag Sonstebo wrote:
>> All,
>>
>> since we've added CloudStack documentation to the discussion topics
>> for the Montreal meetup I wanted to gauge peoples opinion on areas of
>> improvement.
>>
>> Personally I would like to see the following:
>>
>> 1. Overall documentation navigation needs to be improved.
>> 2. Ideally all documentation should be under a single
>> documentation tree with a single table of contents. All content
>> should be searchable without having to visit each of the current
>> documentation roots separately (Getting Started / Installation Guide
>> / Admin Guide / Release Notes).
>> 3. Advanced topics should be moved away from the "Getting Started
>> Docs". The people reading the getting started / concepts sections are
>> typically new CloudStack users who will easily be put off by
>> immediately being presented with advanced topics.
>> 4. API documentation to be a chapter of the Developers guide.
>> 5. Upgrade instructions to be moved from the release notes to the
>> installation guide.
>> 6. Compatibility matrix in single location only – i.e. not in
>> both the release notes and installation guide as this has caused
>> discrepancies in the past.
>>
>> I appreciate we are also working against multiple Github repositories
>> which complicates things slightly, but if we can overall improve the
>> end user experience this is worth the effort.
>>
>> Thoughts?
>>
>> Regards,
>>
>> Dag.Sonstebo@shapeblue.com<ma...@shapeblue.com>
>> www.shapeblue.com<http://www.shapeblue.com>
>> 53 Chandos Place, Covent Garden, London WC2N 4HSUK @shapeblue
>>
>>
>
>
--
Ron Wheeler
President
Artifact Software Inc
email: rwheeler@artifact-software.com<ma...@artifact-software.com>
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
DISCLAIMER
==========
This e-mail may contain privileged and confidential information which is the property of Accelerite, a Persistent Systems business. It is intended only for the use of the individual or entity to which it is addressed. If you are not the intended recipient, you are not authorized to read, retain, copy, print, distribute or use this message. If you have received this communication in error, please notify the sender and delete all copies of this message. Accelerite, a Persistent Systems business does not accept any liability for virus infected mails.
Re: [Discuss] CloudStack documentation
Posted by Ron Wheeler <rw...@artifact-software.com>.
Identify where most issues are raised in the ML and fix the docs to
reduce the confusion.
I suspect that Networking is the source of most problems but perhaps
other have a better sense of this.
Ron
On 19/05/2016 8:29 AM, Ron Wheeler wrote:
> Removal of duplicate information as part of item 2 . Item 5 has this
> implicitly.
>
> Item 3 +1
>
> "Marketing" information targeted at SMB market.
>
> Ron
>
> On 19/05/2016 6:54 AM, Dag Sonstebo wrote:
>> All,
>>
>> since we've added CloudStack documentation to the discussion topics
>> for the Montreal meetup I wanted to gauge peoples opinion on areas of
>> improvement.
>>
>> Personally I would like to see the following:
>>
>> 1. Overall documentation navigation needs to be improved.
>> 2. Ideally all documentation should be under a single
>> documentation tree with a single table of contents. All content
>> should be searchable without having to visit each of the current
>> documentation roots separately (Getting Started / Installation Guide
>> / Admin Guide / Release Notes).
>> 3. Advanced topics should be moved away from the "Getting Started
>> Docs". The people reading the getting started / concepts sections are
>> typically new CloudStack users who will easily be put off by
>> immediately being presented with advanced topics.
>> 4. API documentation to be a chapter of the Developers guide.
>> 5. Upgrade instructions to be moved from the release notes to the
>> installation guide.
>> 6. Compatibility matrix in single location only \u2013 i.e. not in
>> both the release notes and installation guide as this has caused
>> discrepancies in the past.
>>
>> I appreciate we are also working against multiple Github repositories
>> which complicates things slightly, but if we can overall improve the
>> end user experience this is worth the effort.
>>
>> Thoughts?
>>
>> Regards,
>>
>> Dag.Sonstebo@shapeblue.com
>> www.shapeblue.com
>> 53 Chandos Place, Covent Garden, London WC2N 4HSUK
>> @shapeblue
>>
>>
>
>
--
Ron Wheeler
President
Artifact Software Inc
email: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
Re: [Discuss] CloudStack documentation
Posted by Ron Wheeler <rw...@artifact-software.com>.
Removal of duplicate information as part of item 2 . Item 5 has this
implicitly.
Item 3 +1
"Marketing" information targeted at SMB market.
Ron
On 19/05/2016 6:54 AM, Dag Sonstebo wrote:
> All,
>
> since we've added CloudStack documentation to the discussion topics for the Montreal meetup I wanted to gauge peoples opinion on areas of improvement.
>
> Personally I would like to see the following:
>
> 1. Overall documentation navigation needs to be improved.
> 2. Ideally all documentation should be under a single documentation tree with a single table of contents. All content should be searchable without having to visit each of the current documentation roots separately (Getting Started / Installation Guide / Admin Guide / Release Notes).
> 3. Advanced topics should be moved away from the "Getting Started Docs". The people reading the getting started / concepts sections are typically new CloudStack users who will easily be put off by immediately being presented with advanced topics.
> 4. API documentation to be a chapter of the Developers guide.
> 5. Upgrade instructions to be moved from the release notes to the installation guide.
> 6. Compatibility matrix in single location only \u2013 i.e. not in both the release notes and installation guide as this has caused discrepancies in the past.
>
> I appreciate we are also working against multiple Github repositories which complicates things slightly, but if we can overall improve the end user experience this is worth the effort.
>
> Thoughts?
>
> Regards,
>
> Dag.Sonstebo@shapeblue.com
> www.shapeblue.com
> 53 Chandos Place, Covent Garden, London WC2N 4HSUK
> @shapeblue
>
>
--
Ron Wheeler
President
Artifact Software Inc
email: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102