cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ron Wheeler <rwhee...@artifact-software.com>
Subject Re: [Discuss] CloudStack documentation
Date Fri, 20 May 2016 17:50:45 GMT
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:
>
> •       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.


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


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message