On 廿十七年五月廿四日 朝 09:38, Rochelle Grober wrote:
From: Ildiko
> On 2017. May 23., at 15:43, Sean McGinnis <sean.mcgin...@gmx.com>
wrote:
On Mon, May 22, 2017 at 05:50:50PM -0500, Anne Gentle wrote:
On Mon, May 22, 2017 at 5:41 PM, Sean McGinnis
<sean.mcgin...@gmx.com>
wrote:
[snip]
Hey Sean, is the "right to merge" the top difficulty you envision
with 1 or 2? Or is it finding people to do the writing and reviews?
Curious about your thoughts and if you have some experience with
specific day-to-day behavior here, I would love your insights.
Anne
I think it's more about finding people to do the writing and reviews,
though having incentives like having more say in that area of things
could be beneficial for finding those people.
I think it is important to note here that by having the documentation (in it’s
easily identifiable, own folder) living together with the code in the same
repository you have the developer(s) of the feature as first line candidates
on adding documentation to their change.
I know that writing good technical documentation is it’s own profession, but
having the initial data there which can be fixed by experienced writers if
needed is a huge win compared to anything separated, where you might not
have any documentation at all.
So by having the ability to -1 a change because of the lack of documentation
is on one hand might be a process change for reviewers, but gives you the
docs contributors as well.
Possible side benefits here: If a new, wannabe developer starts with the docs
to figure out how to participate in the project, they may/will (if encouraged)
file bugs against the docs where they are wrong or lacking. Beyond that, if
the newbie is reading the code s/he may just fix some low hanging fruit docs
issues, or even go deeper. I know, devs don't read docs, but I think they
sneak looks when they think no one is looking. And then get infuriated if the
docs don't match the code. Perusers of code have more time to address issues
than firefighters (fixing high priority bugs), so it's possible that this new
approach will encourage more complete documentation. I can be optimistic, too.
+1, contributing to documentation should be a much easier starting point
than code & a good way to learn the gerrit workflow. If the doc patch
coming in from the newbie is "better than what's there", it should be
merged swiftly.
--Rocky
So to summarize, the changes what Alex described do not indicate that the
core team has to write the documentation themselves or finding a team of
technical writers before applying the changes, but be conscious about caring
whether docs is added along with the code changes.
Thanks,
Ildikó
__________________________________________________________
________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-
requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
