Open Stack

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 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



>
>>
>>> Personally, I think option 2 or 3 are more realistic, for now. It does
>> mean that an extra build would have to be maintained, but it retains that
>> key differentiator between what is user and developer documentation and
>> involves fewer changes to existing published contents and build jobs. I
>> definitely think option 1 is feasible, and would be happy to make it work
>> if the community prefers this. We could also view option 1 as the
>> longer-term goal, and option 2 as an incremental step toward it (option 3
>> would make option 1 more complicated to achieve).
>>>
>>> What does everyone think of the proposed options? Questions? Other
>> thoughts?
>>>
>>> Cheers,
>>>
>>> Alex
>>>
>>>
>>
>>> ____________________________________________________________
>> ______________
>>> OpenStack Development Mailing List (not for usage questions)
>>> Unsubscribe: OpenStack-dev-request at 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-request at lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
>
> -- 
>
> Read my blog: justwrite.click <https://justwriteclick.com>
> Subscribe to Docs|Code: docslikecode.com


> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20170522/30842f3f/attachment.sig>