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
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" 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
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.vit...@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" 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
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
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:t...@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
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.puthiyet...@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:t...@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
Please give us some examples .. -Original Message- From: Ahmad Emneina [mailto:aemne...@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.puthiyet...@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:t...@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
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.puthiyet...@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:t...@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
On Sep 5, 2013, at 1:11 AM, Prasanna Santhanam 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.puthiyet...@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:t...@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
+1 on "no docs, no submit" Kind Regards Giles D: +44 20 3603 0541 | M: +44 796 111 2055 giles.sir...@shapeblue.com -Original Message- From: Sebastien Goasguen [mailto:run...@gmail.com] Sent: 05 September 2013 07:14 To: dev@cloudstack.apache.org Cc: aemne...@gmail.com Subject: Re: documentation/wiki is a mess On Sep 5, 2013, at 1:11 AM, Prasanna Santhanam 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.puthiyet...@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:t...@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
-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 wrote: > +1 on "no docs, no submit" > > Kind Regards > Giles > > D: +44 20 3603 0541 | M: +44 796 111 2055 > giles.sir...@shapeblue.com > > > > > -Original Message- > From: Sebastien Goasguen [mailto:run...@gmail.com] > Sent: 05 September 2013 07:14 > To: dev@cloudstack.apache.org > Cc: aemne...@gmail.com > Subject: Re: documentation/wiki is a mess > > > On Sep 5, 2013, at 1:11 AM, Prasanna Santhanam 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.puthiyet...@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:t...@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
On Thu, Sep 5, 2013 at 7:00 AM, Daan Hoogland 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
On 09/05/2013 07:56 AM, David Nalley wrote: On Thu, Sep 5, 2013 at 7:00 AM, Daan Hoogland 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
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 wrote: > On 09/05/2013 07:56 AM, David Nalley wrote: > >> On Thu, Sep 5, 2013 at 7:00 AM, Daan Hoogland >> 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
+1 to Marty. On Fri, Sep 6, 2013 at 2:32 AM, Marty Sweet 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.sheph...@gmail.com > > wrote: > > > On 09/05/2013 07:56 AM, David Nalley wrote: > > > >> On Thu, Sep 5, 2013 at 7:00 AM, Daan Hoogland > >> 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
+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 wrote: > +1 to Marty. > > > On Fri, Sep 6, 2013 at 2:32 AM, Marty Sweet 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.sheph...@gmail.com >> > wrote: >> >> > On 09/05/2013 07:56 AM, David Nalley wrote: >> > >> >> On Thu, Sep 5, 2013 at 7:00 AM, Daan Hoogland >> >> 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 >> > >> > >>