cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marty Sweet <msweet....@gmail.com>
Subject Re: documentation/wiki is a mess
Date Fri, 06 Sep 2013 06:32:34 GMT
My view is that when a feature is added the developer should give a short
overview of how to use all of the items which have been added, a doc
contributor can then write this up in a user friendly manner which is
similar to the whole style of the rest of the documentation.

Example description of documentation subtask on feature bug:
-> Click Storage Tab
-> Click on the volume you require
-> Click the 'Resize Volume' icon, this may only appear if xyz
-> Put in a value
 -> If it's less then it will shrink, causing xyz
 -> If it's more then it will expand, although the user must expand the
filesystem in the OS (This then would create another document, as the
process differs on win/linux)

The doc contributor then has a useful set of notes for reference, so they
don't have to spend lots of time trying to workout the in's and out's of a
implemented feature.

Marty


On Thu, Sep 5, 2013 at 5:16 PM, Darren Shepherd <darren.s.shepherd@gmail.com
> wrote:

> On 09/05/2013 07:56 AM, David Nalley wrote:
>
>> On Thu, Sep 5, 2013 at 7:00 AM, Daan Hoogland <daan.hoogland@gmail.com>
>> wrote:
>>
>>> -1 on no docs no submits.
>>>
>>> Docs are important to people that need a contribution they didn't
>>> write themselves. The first ones are the ones to write docs where
>>> missing. You contribute because you need code, not because you need
>>> docs on it.
>>>
>>>
>> If the developer who wrote the code for a feature can't tell me (or
>> the rest of the userbase) how it works and how to use it, then I
>> question exactly how useful the feature is.
>>
>>
> Everyone should be on the hook to document in some fashion.  The doc
> writer are usually just better at it.
>
> So as somebody who is more dev focused, I just don't know where to put
> things.  I'm not about to touch the XML docs.  That seems like a doc team's
> domain.
>
> So personally I'd like to see a bit more organization in the wiki and then
> a clear cut definition of when stuff goes to the XML.  Additional proposals
> and design specs don't count as documenting functionality. Those things are
> just SDLC artifacts.  Frankly I think the current design template should
> have the scope, impact, and QA notes and then link to another place in the
> wiki with the design.  As the development is in progress the wiki page can
> be marked with WIP.
>
> We should be careful about "no X, no commit" policies.  We don't want to
> discourage contributions.  Documentation is useful and if somebody wants to
> contribute then I think they would be inclined to put some documentation
> such that it can be used by other people.  If we make the process easy and
> obvious to do such, I think more documentation will exist.
>
> Darren
>
>

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