+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 <tracp...@mantoso.com> wrote: > +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 >> > >> > >>
