> I prefer option 1, which should be obvious from Anne's reference to my
exiting work to enable that. Option 2 seems yucky (to me) because it adds yet
another docs tree and sphinx config to projects, and thus is counter to my hope
that we'll have one single docs tree per repo.
>
> I disagree with option 3. It seems to be a way to organize the content
simply to wall-off access to parts of it; e.g. docs people can't land stuff in
the code part and potentially some code people can't land stuff in the docs
part. However, docs should always land with the code that changed them.
Separating the docs into a separate repo removes the ability to land docs with
code.
>
> I really like the plan Alex has described about docs team representatives
participating more directly with the projects. If those
+1 for option #1. I strongly believe the best way to keep all a
project's docs up to date with ongoing code changes is to make those
changes to contain in-repo docs updates as well. And here developers
should use the chance and benefit from rich experience of docs team
representatives, as no one else knows more about writing technical
documentation best practices!
I must admit, I’m quite surprised by everyone’s preference for option 1.
Although not disappointed. I’m interested to see where and how this goes!
Pros:
* Code review shall cover docs changes and code changes at once, which
is great
+1000 to this. This is a lot of what I’m pushing for. Teams that have already
implemented our project-specific installation guides say this as their #1
feedback.
I’m hoping we can get more positive responses for this too.
* Docs team contributors may choose to start acting as representatives,
which is become mentors and/or "docs guarding sentries" rather than
technical writers. This offloads writing to projects' devs and perhaps
resolves the issue as mentoring/reviewing requires less time, or more haha.
* Developers shall become technical docs writers as well, that's a
really exciting perspective to advance and know more about your
projects! And, who knows, this as well may end up bringing more man
power to the docs team, after all.
Cons:
there are none, let's be optimistic! Developers love document changes
for code, we all know that.
Haha amazing! No cons! I guess my only concern is that this going to be a *lot*
of work, and it can’t just fall on the doc team. We will have to move all the
documentation to the appropriate repos, and build this infrastructure. As
previously noted, there has been a dip in contributions to dev and doc, and
it’s been hard to get people to work as CPLs to the doc team.
Do we think it is possible to make this a goal for the cycle across the board,
and ensure we have this completed by $RELEASE?
representatives should be able to add a +2 or -2 to project patches,
then make those representatives core reviewers for the respective
project. Like every other core reviewer, they should be trusted to use
good judgement for choosing what to review and what score to give it.
So, I’ve been a docs core for the OpenStack-Ansible project for some time now
and this works really well within our structure. I do not merge anything unless
it has a dev +2 before I come along (unless it is a trivial doc-only
spelling/grammar change). I think there is a lot of community fear that if you
give a writer core status on a project, that they’re just going to run wild and
pass things they don’t understand. I can’t speak for everyone, but I can say
that this has been working really well in the OSA community. We now have 3 doc
cores.
__________________________________________________________________________
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
