[openstack-dev] [doc][ptls][all] Documentation publishing future

Alexandra Settle a.settle at outlook.com
Tue May 23 12:35:55 UTC 2017

    > 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!
    * 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.
    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. 

More information about the OpenStack-dev mailing list