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
