cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rajsekhar K <rajsekha...@accelerite.com>
Subject RE: [Discuss] CloudStack documentation
Date Fri, 20 May 2016 14:43:19 GMT
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<mailto:rajsekhar.k@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<mailto:Dag.Sonstebo@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<mailto:rwheeler@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.
Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message