Thanks for taking an interest. I've got lots of replies to catch up on. Tim O'Brien wrote: > Developers don't write great documentation. Don't raise the bar so high > that people are discouraged from submitting doco-less patches. Just create > a structure to address documentation deficiency.
I wasn't aiming to discourage submitting patches, that's why I said "even if it is very rough for someone to expand on later. While rough is acceptable, incomplete is not." > > 1. Create a documentation posse - identify people who will focus solely on > doco, reduce the barriers for them to commit. Or, move documentation to an > external project with lower barriers to entry. You can't just do new DocumentationPosse().startInBackground(); People need to be interested. In all honestly, I've seen maybe 2 or 3 specifically interested and it in all the time I've been here. I think we all need to lift our own games, to make tying it together achievable. We should put the call out, though. Are you volunteering to lead the posse? :) As for lowering barriers - what exact barriers do you think there are, and how can we lower them. Creating a separate project is unnecessary (the doc should go where it should go, access can be granted accordingly). We can't just hand out commit access like candy - people need to show they know what they are doing and are going to stick around just like anyone else. The only barrier I see is to apply patches immediately as they are at greater risk of getting stale. I've been doing this recently. > > 2. Consider a separate list - people removed from the development process > produce better documentation. I absolutely disagree. The developers will stop participating in documentation altogether. The documenters need to know how development affects them. The two need to be closely related. Do you have any factual basis or data for the statement to contradict this? > > 3. Add "Waiting for Documentation" as a stage in a customized JIRA > workflow. Instead of creating separate issues for "Document what I just did > in the Site Plugin", give developers the opportunity to just mark something > as implemented but undocumented (otherwise know n as useless and invisible) I don't think a workflow step is very helpful, myself. I'd say let people go at it and decide on the best way to mark them through experience. So far, I think the use of components suffice. I'd rather add a custom field than a workflow state. - Brett --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
