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

Bogdan Dobrelya bdobreli at redhat.com
Tue May 23 08:45:08 UTC 2017


On 23.05.2017 2:20, John Dickinson wrote:
> 
> 
> On 22 May 2017, at 15:50, Anne Gentle wrote:
> 
>> On Mon, May 22, 2017 at 5:41 PM, Sean McGinnis <sean.mcginnis at gmx.com>
>> wrote:
>>
>>> On Mon, May 22, 2017 at 09:39:09AM +0000, Alexandra Settle wrote:
>>>
>>> [snip]
>>>
>>>> 1. We could combine all of the documentation builds, so that each
>>> project has a single doc/source directory that includes developer,
>>> contributor, and user documentation. This option would reduce the number of
>>> build jobs we have to run, and cut down on the number of separate sphinx
>>> configurations in each repository. It would completely change the way we
>>> publish the results, though, and we would need to set up redirects from all
>>> of the existing locations to the new locations and move all of the existing
>>> documentation under the new structure.
>>>>
>>>> 2. We could retain the existing trees for developer and API docs, and
>>> add a new one for "user" documentation. The installation guide,
>>> configuration guide, and admin guide would move here for all projects.
>>> Neutron's user documentation would include the current networking guide as
>>> well. This option would add 1 new build to each repository, but would allow
>>> us to easily roll out the change with less disruption in the way the site
>>> is organized and published, so there would be less work in the short term.
>>>>
>>>> 3. We could do option 2, but use a separate repository for the new
>>> user-oriented documentation. This would allow project teams to delegate
>>> management of the documentation to a separate review project-sub-team, but
>>> would complicate the process of landing code and documentation updates
>>> together so that the docs are always up to date.
>>>>
>>>
>>> I actually like the first two a little better, but I think this might
>>> actually be the best option. My hope
>>> would be that there could continue to be a docs team that can help out
>>> with some of this, and by having a
>>> separate repo it would allow usto set up separate teams with rights to
>>> merge.
>>>
>>
>> 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 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!

Pros:
* Code review shall cover docs changes and code changes at once, which
is great
* 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.

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.
> 
> Let's work towards option 1. Although I think option 2 is largely orthogonal to option 1 (i.e. the "user" docs should be merged into the project trees regardless of unification of the various in-project docs trees), it can happen before or after option 1 is done.
> 
> 
> --John
> 


-- 
Best regards,
Bogdan Dobrelya,
Irc #bogdando



More information about the OpenStack-dev mailing list