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: [email protected]<mailto:[email protected]>
-----Original Message-----
From: Ron Wheeler [mailto:[email protected]]
Sent: Thursday, May 19, 2016 6:17 PM
To: [email protected]
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,
>>
>> [email protected]<mailto:[email protected]>
>> www.shapeblue.com<http://www.shapeblue.com>
>> 53 Chandos Place, Covent Garden, London WC2N 4HSUK @shapeblue
>>
>>
>
>
--
Ron Wheeler
President
Artifact Software Inc
email: [email protected]<mailto:[email protected]>
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.
