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 > >
