+1 to Marty.
On Fri, Sep 6, 2013 at 2:32 AM, Marty Sweet <msweet....@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.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 <daan.hoogl...@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 > > > > >
