You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by Darren Shepherd <da...@gmail.com> on 2013/09/03 20:10:28 UTC
documentation/wiki is a mess
The state of documentation and especially the wiki is a mess. I'd like
to help clean this up, but I can't seem to reconcile the difference
between the XML documentation and the wiki. Personally I feel the wiki
should be for development. The XML should be installation and admin
guides only.
Additionally, another general complaint I have is that features are
basically only documented in the "4.x Design Documents" sections. This
is not very useful and makes it impossible to find anything.
Additionally those documents are really more a statement of work. There
should be a section for the design of cloudstack, organized into
functional areas. So one can actually navigate the design.
The state of documentation of an open source projects says a lot about
the community that develops it...
Darren
RE: documentation/wiki is a mess
Posted by Radhika Puthiyetath <ra...@citrix.com>.
Please give us some examples ..
-----Original Message-----
From: Ahmad Emneina [mailto:aemneina@gmail.com]
Sent: Thursday, September 05, 2013 10:22 AM
To: dev@cloudstack.apache.org
Subject: Re: documentation/wiki is a mess
I think prasanna hit the nail on the head. I'm sure there are features there no one knows about, or ever will...
+1 for developers documenting what features/functions are abound.
On Wed, Sep 4, 2013 at 9:36 PM, Radhika Puthiyetath < radhika.puthiyetath@citrix.com> wrote:
> Hi,
>
> We do not have a doc team as such :-)
>
> We have a set of doc contributors that so far have not worked as a team.
> Probably, we should think about aligning the doc efforts and having a
> process and style guide in place.
>
> If the FS is good enough, we need not trouble the code committers to
> write own docs is what I feel.
>
> Regards
> -Radhika
>
> -----Original Message-----
> From: Prasanna Santhanam [mailto:tsp@apache.org]
> Sent: Thursday, September 05, 2013 9:34 AM
> To: dev@cloudstack.apache.org
> Subject: Re: documentation/wiki is a mess
>
> On Tue, Sep 03, 2013 at 11:10:28AM -0700, Darren Shepherd wrote:
> >
> > The state of documentation of an open source projects says a lot
> > about the community that develops it...
> >
>
> Esp. for XML documentation: I say we write our own docs if we want our
> feature to be used. Or it dies a natural death in quiet isolation with
> no one ever using it. Docs team can handle the editing and organizing bits.
> That should go for Wikis too. If you want the wiki to be useful then
> write it, organize it and maintain it. Don't just put it there to fill
> a template. It'll never recieve any love.
>
> --
> Prasanna.,
>
> ------------------------
> Powered by BigRock.com
>
>
Re: documentation/wiki is a mess
Posted by Daan Hoogland <da...@gmail.com>.
+1 to Darren's 'We should be careful about "no X, no commit"' One
exception though; (unit)tests. And I can live with a #!human script
like Marty describes. Even though your point is valid, David,
developers (like me) have an internal company need for a fix or a
feature, and are inclined to work on it as priority shifts. It is not
a good idea to allow for features only as they are becoming proven
technology. When done they are done. When used they become documented.
When unused they will eventually leave the code base again.
no rant intended,
Daan
On Fri, Sep 6, 2013 at 3:42 PM, Tracy Phillips <tr...@mantoso.com> wrote:
> +1 to Marty.
>
>
> On Fri, Sep 6, 2013 at 2:32 AM, Marty Sweet <ms...@gmail.com> wrote:
>
>> 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 <da...@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
>> >
>> >
>>
Re: documentation/wiki is a mess
Posted by Tracy Phillips <tr...@mantoso.com>.
+1 to Marty.
On Fri, Sep 6, 2013 at 2:32 AM, Marty Sweet <ms...@gmail.com> wrote:
> 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 <da...@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
> >
> >
>
Re: documentation/wiki is a mess
Posted by Marty Sweet <ms...@gmail.com>.
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 <da...@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
>
>
Re: documentation/wiki is a mess
Posted by Darren Shepherd <da...@gmail.com>.
On 09/05/2013 07:56 AM, David Nalley wrote:
> On Thu, Sep 5, 2013 at 7:00 AM, Daan Hoogland <da...@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
Re: documentation/wiki is a mess
Posted by David Nalley <da...@gnsa.us>.
On Thu, Sep 5, 2013 at 7:00 AM, Daan Hoogland <da...@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.
Re: documentation/wiki is a mess
Posted by Daan Hoogland <da...@gmail.com>.
-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.
On Thu, Sep 5, 2013 at 9:25 AM, Giles Sirett <gi...@shapeblue.com> wrote:
> +1 on "no docs, no submit"
>
> Kind Regards
> Giles
>
> D: +44 20 3603 0541 | M: +44 796 111 2055
> Giles.Sirett@shapeblue.com
>
>
>
>
> -----Original Message-----
> From: Sebastien Goasguen [mailto:runseb@gmail.com]
> Sent: 05 September 2013 07:14
> To: dev@cloudstack.apache.org
> Cc: aemneina@gmail.com
> Subject: Re: documentation/wiki is a mess
>
>
> On Sep 5, 2013, at 1:11 AM, Prasanna Santhanam <ts...@apache.org> wrote:
>
>> Radhika, what I meant was everyone should help out with docs. Esp.
>> those working on a feature should care most that the docs for their
>> feature is perfect for an end user to understand, implement and use.
>>
>> We shouldn't piggy-back on those helping fix doc bugs all the time
>> which I see happening too often. Someone files a doc bug and someone
>> else fixes it and someone else reviews it and finally the users are
>> still having trouble understanding it. We're just creating work for
>> ourselves that way.
>>
>> Feature specs have architectural and implementation details and may
>> not often be fully baked by the time the feature starts development.
>> Changes happen during implementation and reviewing our docs after
>> everything is merged is a good forcing-function to fix our docs.
>>
>> I'm +1 for style guides and markdown based docs. They should make this
>> whole process a lot easier for everyone.
>
> I am a big +1 for literally forcing devs to submit docs for user facing features, otherwise the feature does not get added.
> Just like unit tests. No unitests, no commit, no docs, no commit.
> The devs are the best to write the docs of their own feature.
>
>>
>> On Wed, Sep 04, 2013 at 09:52:03PM -0700, Ahmad Emneina wrote:
>>> I think prasanna hit the nail on the head. I'm sure there are
>>> features there no one knows about, or ever will...
>>> +1 for developers documenting what features/functions are abound.
>>>
>>>
>>>
>>> On Wed, Sep 4, 2013 at 9:36 PM, Radhika Puthiyetath <
>>> radhika.puthiyetath@citrix.com> wrote:
>>>
>>>> Hi,
>>>>
>>>> We do not have a doc team as such :-)
>>>>
>>>> We have a set of doc contributors that so far have not worked as a team.
>>>> Probably, we should think about aligning the doc efforts and having
>>>> a process and style guide in place.
>>>>
>>>> If the FS is good enough, we need not trouble the code committers to
>>>> write own docs is what I feel.
>>>>
>>>> Regards
>>>> -Radhika
>>>>
>>>> -----Original Message-----
>>>> From: Prasanna Santhanam [mailto:tsp@apache.org]
>>>> Sent: Thursday, September 05, 2013 9:34 AM
>>>> To: dev@cloudstack.apache.org
>>>> Subject: Re: documentation/wiki is a mess
>>>>
>>>> On Tue, Sep 03, 2013 at 11:10:28AM -0700, Darren Shepherd wrote:
>>>>>
>>>>> The state of documentation of an open source projects says a lot
>>>>> about the community that develops it...
>>>>>
>>>>
>>>> Esp. for XML documentation: I say we write our own docs if we want
>>>> our feature to be used. Or it dies a natural death in quiet
>>>> isolation with no one ever using it. Docs team can handle the editing and organizing bits.
>>>> That should go for Wikis too. If you want the wiki to be useful then
>>>> write it, organize it and maintain it. Don't just put it there to
>>>> fill a template. It'll never recieve any love.
>>>>
>>>> --
>>>> Prasanna.,
>>>>
>>>> ------------------------
>>>> Powered by BigRock.com
>>>>
>>>>
>>
>> --
>> Prasanna.,
>>
>> ------------------------
>> Powered by BigRock.com
>>
>
> This email and any attachments to it may be confidential and are intended solely for the use of the individual to whom it is addressed. Any views or opinions expressed are solely those of the author and do not necessarily represent those of Shape Blue Ltd or related companies. If you are not the intended recipient of this email, you must neither take any action based upon its contents, nor copy or show it to anyone. Please contact the sender if you believe you have received this email in error. Shape Blue Ltd is a company incorporated in England & Wales. ShapeBlue Services India LLP is operated under license from Shape Blue Ltd. ShapeBlue is a registered trademark.
RE: documentation/wiki is a mess
Posted by Giles Sirett <gi...@shapeblue.com>.
+1 on "no docs, no submit"
Kind Regards
Giles
D: +44 20 3603 0541 | M: +44 796 111 2055
Giles.Sirett@shapeblue.com
-----Original Message-----
From: Sebastien Goasguen [mailto:runseb@gmail.com]
Sent: 05 September 2013 07:14
To: dev@cloudstack.apache.org
Cc: aemneina@gmail.com
Subject: Re: documentation/wiki is a mess
On Sep 5, 2013, at 1:11 AM, Prasanna Santhanam <ts...@apache.org> wrote:
> Radhika, what I meant was everyone should help out with docs. Esp.
> those working on a feature should care most that the docs for their
> feature is perfect for an end user to understand, implement and use.
>
> We shouldn't piggy-back on those helping fix doc bugs all the time
> which I see happening too often. Someone files a doc bug and someone
> else fixes it and someone else reviews it and finally the users are
> still having trouble understanding it. We're just creating work for
> ourselves that way.
>
> Feature specs have architectural and implementation details and may
> not often be fully baked by the time the feature starts development.
> Changes happen during implementation and reviewing our docs after
> everything is merged is a good forcing-function to fix our docs.
>
> I'm +1 for style guides and markdown based docs. They should make this
> whole process a lot easier for everyone.
I am a big +1 for literally forcing devs to submit docs for user facing features, otherwise the feature does not get added.
Just like unit tests. No unitests, no commit, no docs, no commit.
The devs are the best to write the docs of their own feature.
>
> On Wed, Sep 04, 2013 at 09:52:03PM -0700, Ahmad Emneina wrote:
>> I think prasanna hit the nail on the head. I'm sure there are
>> features there no one knows about, or ever will...
>> +1 for developers documenting what features/functions are abound.
>>
>>
>>
>> On Wed, Sep 4, 2013 at 9:36 PM, Radhika Puthiyetath <
>> radhika.puthiyetath@citrix.com> wrote:
>>
>>> Hi,
>>>
>>> We do not have a doc team as such :-)
>>>
>>> We have a set of doc contributors that so far have not worked as a team.
>>> Probably, we should think about aligning the doc efforts and having
>>> a process and style guide in place.
>>>
>>> If the FS is good enough, we need not trouble the code committers to
>>> write own docs is what I feel.
>>>
>>> Regards
>>> -Radhika
>>>
>>> -----Original Message-----
>>> From: Prasanna Santhanam [mailto:tsp@apache.org]
>>> Sent: Thursday, September 05, 2013 9:34 AM
>>> To: dev@cloudstack.apache.org
>>> Subject: Re: documentation/wiki is a mess
>>>
>>> On Tue, Sep 03, 2013 at 11:10:28AM -0700, Darren Shepherd wrote:
>>>>
>>>> The state of documentation of an open source projects says a lot
>>>> about the community that develops it...
>>>>
>>>
>>> Esp. for XML documentation: I say we write our own docs if we want
>>> our feature to be used. Or it dies a natural death in quiet
>>> isolation with no one ever using it. Docs team can handle the editing and organizing bits.
>>> That should go for Wikis too. If you want the wiki to be useful then
>>> write it, organize it and maintain it. Don't just put it there to
>>> fill a template. It'll never recieve any love.
>>>
>>> --
>>> Prasanna.,
>>>
>>> ------------------------
>>> Powered by BigRock.com
>>>
>>>
>
> --
> Prasanna.,
>
> ------------------------
> Powered by BigRock.com
>
This email and any attachments to it may be confidential and are intended solely for the use of the individual to whom it is addressed. Any views or opinions expressed are solely those of the author and do not necessarily represent those of Shape Blue Ltd or related companies. If you are not the intended recipient of this email, you must neither take any action based upon its contents, nor copy or show it to anyone. Please contact the sender if you believe you have received this email in error. Shape Blue Ltd is a company incorporated in England & Wales. ShapeBlue Services India LLP is operated under license from Shape Blue Ltd. ShapeBlue is a registered trademark.
Re: documentation/wiki is a mess
Posted by Sebastien Goasguen <ru...@gmail.com>.
On Sep 5, 2013, at 1:11 AM, Prasanna Santhanam <ts...@apache.org> wrote:
> Radhika, what I meant was everyone should help out with docs. Esp.
> those working on a feature should care most that the docs for their
> feature is perfect for an end user to understand, implement and use.
>
> We shouldn't piggy-back on those helping fix doc bugs all the time
> which I see happening too often. Someone files a doc bug and someone
> else fixes it and someone else reviews it and finally the users are
> still having trouble understanding it. We're just creating work for
> ourselves that way.
>
> Feature specs have architectural and implementation details and may
> not often be fully baked by the time the feature starts development.
> Changes happen during implementation and reviewing our docs after
> everything is merged is a good forcing-function to fix our docs.
>
> I'm +1 for style guides and markdown based docs. They should make this
> whole process a lot easier for everyone.
I am a big +1 for literally forcing devs to submit docs for user facing features, otherwise the feature does not get added.
Just like unit tests. No unitests, no commit, no docs, no commit.
The devs are the best to write the docs of their own feature.
>
> On Wed, Sep 04, 2013 at 09:52:03PM -0700, Ahmad Emneina wrote:
>> I think prasanna hit the nail on the head. I'm sure there are features
>> there no one knows about, or ever will...
>> +1 for developers documenting what features/functions are abound.
>>
>>
>>
>> On Wed, Sep 4, 2013 at 9:36 PM, Radhika Puthiyetath <
>> radhika.puthiyetath@citrix.com> wrote:
>>
>>> Hi,
>>>
>>> We do not have a doc team as such :-)
>>>
>>> We have a set of doc contributors that so far have not worked as a team.
>>> Probably, we should think about aligning the doc efforts and having a
>>> process and style guide in place.
>>>
>>> If the FS is good enough, we need not trouble the code committers to write
>>> own docs is what I feel.
>>>
>>> Regards
>>> -Radhika
>>>
>>> -----Original Message-----
>>> From: Prasanna Santhanam [mailto:tsp@apache.org]
>>> Sent: Thursday, September 05, 2013 9:34 AM
>>> To: dev@cloudstack.apache.org
>>> Subject: Re: documentation/wiki is a mess
>>>
>>> On Tue, Sep 03, 2013 at 11:10:28AM -0700, Darren Shepherd wrote:
>>>>
>>>> The state of documentation of an open source projects says a lot about
>>>> the community that develops it...
>>>>
>>>
>>> Esp. for XML documentation: I say we write our own docs if we want our
>>> feature to be used. Or it dies a natural death in quiet isolation with no
>>> one ever using it. Docs team can handle the editing and organizing bits.
>>> That should go for Wikis too. If you want the wiki to be useful then write
>>> it, organize it and maintain it. Don't just put it there to fill a
>>> template. It'll never recieve any love.
>>>
>>> --
>>> Prasanna.,
>>>
>>> ------------------------
>>> Powered by BigRock.com
>>>
>>>
>
> --
> Prasanna.,
>
> ------------------------
> Powered by BigRock.com
>
Re: documentation/wiki is a mess
Posted by Prasanna Santhanam <ts...@apache.org>.
Radhika, what I meant was everyone should help out with docs. Esp.
those working on a feature should care most that the docs for their
feature is perfect for an end user to understand, implement and use.
We shouldn't piggy-back on those helping fix doc bugs all the time
which I see happening too often. Someone files a doc bug and someone
else fixes it and someone else reviews it and finally the users are
still having trouble understanding it. We're just creating work for
ourselves that way.
Feature specs have architectural and implementation details and may
not often be fully baked by the time the feature starts development.
Changes happen during implementation and reviewing our docs after
everything is merged is a good forcing-function to fix our docs.
I'm +1 for style guides and markdown based docs. They should make this
whole process a lot easier for everyone.
On Wed, Sep 04, 2013 at 09:52:03PM -0700, Ahmad Emneina wrote:
> I think prasanna hit the nail on the head. I'm sure there are features
> there no one knows about, or ever will...
> +1 for developers documenting what features/functions are abound.
>
>
>
> On Wed, Sep 4, 2013 at 9:36 PM, Radhika Puthiyetath <
> radhika.puthiyetath@citrix.com> wrote:
>
> > Hi,
> >
> > We do not have a doc team as such :-)
> >
> > We have a set of doc contributors that so far have not worked as a team.
> > Probably, we should think about aligning the doc efforts and having a
> > process and style guide in place.
> >
> > If the FS is good enough, we need not trouble the code committers to write
> > own docs is what I feel.
> >
> > Regards
> > -Radhika
> >
> > -----Original Message-----
> > From: Prasanna Santhanam [mailto:tsp@apache.org]
> > Sent: Thursday, September 05, 2013 9:34 AM
> > To: dev@cloudstack.apache.org
> > Subject: Re: documentation/wiki is a mess
> >
> > On Tue, Sep 03, 2013 at 11:10:28AM -0700, Darren Shepherd wrote:
> > >
> > > The state of documentation of an open source projects says a lot about
> > > the community that develops it...
> > >
> >
> > Esp. for XML documentation: I say we write our own docs if we want our
> > feature to be used. Or it dies a natural death in quiet isolation with no
> > one ever using it. Docs team can handle the editing and organizing bits.
> > That should go for Wikis too. If you want the wiki to be useful then write
> > it, organize it and maintain it. Don't just put it there to fill a
> > template. It'll never recieve any love.
> >
> > --
> > Prasanna.,
> >
> > ------------------------
> > Powered by BigRock.com
> >
> >
--
Prasanna.,
------------------------
Powered by BigRock.com
Re: documentation/wiki is a mess
Posted by Ahmad Emneina <ae...@gmail.com>.
I think prasanna hit the nail on the head. I'm sure there are features
there no one knows about, or ever will...
+1 for developers documenting what features/functions are abound.
On Wed, Sep 4, 2013 at 9:36 PM, Radhika Puthiyetath <
radhika.puthiyetath@citrix.com> wrote:
> Hi,
>
> We do not have a doc team as such :-)
>
> We have a set of doc contributors that so far have not worked as a team.
> Probably, we should think about aligning the doc efforts and having a
> process and style guide in place.
>
> If the FS is good enough, we need not trouble the code committers to write
> own docs is what I feel.
>
> Regards
> -Radhika
>
> -----Original Message-----
> From: Prasanna Santhanam [mailto:tsp@apache.org]
> Sent: Thursday, September 05, 2013 9:34 AM
> To: dev@cloudstack.apache.org
> Subject: Re: documentation/wiki is a mess
>
> On Tue, Sep 03, 2013 at 11:10:28AM -0700, Darren Shepherd wrote:
> >
> > The state of documentation of an open source projects says a lot about
> > the community that develops it...
> >
>
> Esp. for XML documentation: I say we write our own docs if we want our
> feature to be used. Or it dies a natural death in quiet isolation with no
> one ever using it. Docs team can handle the editing and organizing bits.
> That should go for Wikis too. If you want the wiki to be useful then write
> it, organize it and maintain it. Don't just put it there to fill a
> template. It'll never recieve any love.
>
> --
> Prasanna.,
>
> ------------------------
> Powered by BigRock.com
>
>
RE: documentation/wiki is a mess
Posted by Radhika Puthiyetath <ra...@citrix.com>.
Hi,
We do not have a doc team as such :-)
We have a set of doc contributors that so far have not worked as a team. Probably, we should think about aligning the doc efforts and having a process and style guide in place.
If the FS is good enough, we need not trouble the code committers to write own docs is what I feel.
Regards
-Radhika
-----Original Message-----
From: Prasanna Santhanam [mailto:tsp@apache.org]
Sent: Thursday, September 05, 2013 9:34 AM
To: dev@cloudstack.apache.org
Subject: Re: documentation/wiki is a mess
On Tue, Sep 03, 2013 at 11:10:28AM -0700, Darren Shepherd wrote:
>
> The state of documentation of an open source projects says a lot about
> the community that develops it...
>
Esp. for XML documentation: I say we write our own docs if we want our feature to be used. Or it dies a natural death in quiet isolation with no one ever using it. Docs team can handle the editing and organizing bits. That should go for Wikis too. If you want the wiki to be useful then write it, organize it and maintain it. Don't just put it there to fill a template. It'll never recieve any love.
--
Prasanna.,
------------------------
Powered by BigRock.com
Re: documentation/wiki is a mess
Posted by Prasanna Santhanam <ts...@apache.org>.
On Tue, Sep 03, 2013 at 11:10:28AM -0700, Darren Shepherd wrote:
>
> The state of documentation of an open source projects says a lot
> about the community that develops it...
>
Esp. for XML documentation: I say we write our own docs if we want
our feature to be used. Or it dies a natural death in quiet isolation
with no one ever using it. Docs team can handle the editing and
organizing bits. That should go for Wikis too. If you want the wiki to
be useful then write it, organize it and maintain it. Don't just put it
there to fill a template. It'll never recieve any love.
--
Prasanna.,
------------------------
Powered by BigRock.com
RE: documentation/wiki is a mess
Posted by Soheil Eizadi <se...@infoblox.com>.
Eliminate duplication, recently I updated the wiki about how to install the SystemVM template for development. I found that there are two places where setting up development environment is documented, one was a wiki that I could modify.
-Soheil
https://cwiki.apache.org/confluence/display/CLOUDSTACK/How+to+build+CloudStack
http://cloudstack.apache.org/develop/environment.html
________________________________________
From: Chiradeep Vittal [Chiradeep.Vittal@citrix.com]
Sent: Tuesday, September 03, 2013 11:33 AM
To: dev@cloudstack.apache.org
Subject: Re: documentation/wiki is a mess
The wiki is also for users as content gets added between releases as well.
But the developer content can certainly be reorganized.
On 9/3/13 11:10 AM, "Darren Shepherd" <da...@gmail.com> wrote:
>The state of documentation and especially the wiki is a mess. I'd like
>to help clean this up, but I can't seem to reconcile the difference
>between the XML documentation and the wiki. Personally I feel the wiki
>should be for development. The XML should be installation and admin
>guides only.
>
>Additionally, another general complaint I have is that features are
>basically only documented in the "4.x Design Documents" sections. This
>is not very useful and makes it impossible to find anything.
>Additionally those documents are really more a statement of work. There
>should be a section for the design of cloudstack, organized into
>functional areas. So one can actually navigate the design.
>
>The state of documentation of an open source projects says a lot about
>the community that develops it...
>
>Darren
Re: documentation/wiki is a mess
Posted by Chiradeep Vittal <Ch...@citrix.com>.
The wiki is also for users as content gets added between releases as well.
But the developer content can certainly be reorganized.
On 9/3/13 11:10 AM, "Darren Shepherd" <da...@gmail.com> wrote:
>The state of documentation and especially the wiki is a mess. I'd like
>to help clean this up, but I can't seem to reconcile the difference
>between the XML documentation and the wiki. Personally I feel the wiki
>should be for development. The XML should be installation and admin
>guides only.
>
>Additionally, another general complaint I have is that features are
>basically only documented in the "4.x Design Documents" sections. This
>is not very useful and makes it impossible to find anything.
>Additionally those documents are really more a statement of work. There
>should be a section for the design of cloudstack, organized into
>functional areas. So one can actually navigate the design.
>
>The state of documentation of an open source projects says a lot about
>the community that develops it...
>
>Darren