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

[Michael Johnson]

Hi Alex,

 

As you know I am a strong proponent of moving the docs into the project team 
repositories [1].

 

Personally I am in favor of pulling the Band-Aids off and doing option 1.  I 
think centralizing the documentation under one tree and consolidating the build 
into one job has benefits.  I can’t speak to the complexities of the 
documentation template(s?) and the sphinx configuration issues that might arise 
from this plan, but from a PTL/developer/doc writer I like the concept.  I 
fully understand this means work for us to move our API-REF, etc. but I think 
it is worth it.

 

As a secondary vote I am also ok with option 2.  I just think we might as well 
do a full consolidation.

 

I am not a fan of requiring project teams to setup separate repos for the docs, 
there is value to having them in tree for me.  So, I would vote against 3.

 

Michael

 

[1] https://review.openstack.org/#/c/439122/

 

From: Alexandra Settle [mailto:a.set...@outlook.com] 
Sent: Monday, May 22, 2017 2:39 AM
To: OpenStack Development Mailing List (not for usage questions) 
<openstack-dev@lists.openstack.org>
Cc: 'openstack-d...@lists.openstack.org' <openstack-d...@lists.openstack.org>
Subject: [openstack-dev] [doc][ptls][all] Documentation publishing future

 

Hi everyone,

 

The documentation team are rapidly losing key contributors and core reviewers. 
We are not alone, this is happening across the board. It is making things 
harder, but not impossible.

Since our inception in 2010, we’ve been climbing higher and higher trying to 
achieve the best documentation we could, and uphold our high standards. This is 
something to be incredibly proud of.

 

However, we now need to take a step back and realise that the amount of work we 
are attempting to maintain is now out of reach for the team size that we have. 
At the moment we have 13 cores, of whom none are full time contributors or 
reviewers. This includes myself.

 

Until this point, the documentation team has owned several manuals that include 
content related to multiple projects, including an installation guide, admin 
guide, configuration guide, networking guide, and security guide. Because the 
team no longer has the resources to own that content, we want to invert the 
relationship between the doc team and project teams, so that we become liaisons 
to help with maintenance instead of asking for project teams to provide 
liaisons to help with content. As a part of that change, we plan to move the 
existing content out of the central manuals repository, into repositories owned 
by the appropriate project teams. Project teams will then own the content and 
the documentation team will assist by managing the build tools, helping with 
writing guidelines and style, but not writing the bulk of the text.

 

We currently have the infrastructure set up to empower project teams to manage 
their own documentation in their own tree, and many do. As part of this change, 
the rest of the existing content from the install guide and admin guide will 
also move into project-owned repositories. We have a few options for how to 
implement the move, and that's where we need feedback now.

 

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.

 

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 

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

[John Garbutt]

On Mon, 22 May 2017 at 10:43, Alexandra Settle  wrote:
> We could also view option 1 as the longer-term goal,
> and option 2 as an incremental step toward it

+1 doing option 2 then option 1.
It just seems a good way to split up the work.

Thanks,
johnthetubaguy
__
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

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

[Tom Fifield]

On 廿十七年五月廿四日 朝 09:38, Rochelle Grober wrote:

  From: Ildiko
  > On 2017. May 23., at 15:43, Sean McGinnis 

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

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

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

[Rochelle Grober]

 From: Ildiko 
 > On 2017. May 23., at 15:43, Sean McGinnis 
> 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
> >> 
> >> 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.

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

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

[Lance Bragstad]

I'm in favor of option #1. I think it encourages our developers to become
better writers with guidance from the docs team. While ensuring docs are
proposed prior to merging the implementation cross-repository is totally
possible, I think #1 makes that flow easier.

Thanks for putting together the options, Alex.

On Tue, May 23, 2017 at 11:02 AM, Ildiko Vancsa 
wrote:

> Hi Alex,
>
> First of all thank you for writing this up the summary and list options
> with their expected impacts.
>
> >
> > 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.
>
> I’m fully in favor for option #1 and/or option #2. From the perspective of
> trying to move step-by-step and give a chance to project teams to
> acclimatize with the changes I think starting with #2 should be sufficient.
>
> Although if we think that option #1 is doable as a starting point and also
> end goal, you have my support for that too.
>
> >
> > 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.
> >
>
> As being one of the advocates on having the documentation living together
> with the code so we can give a chance to the experts of the code changes to
> add the corresponding documentation as well, I'm definitely against option
> #3. :)
>
> Thanks and Best Regards,
> 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

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

[Ildiko Vancsa]

Hi Alex,

First of all thank you for writing this up the summary and list options with 
their expected impacts.

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

I’m fully in favor for option #1 and/or option #2. From the perspective of 
trying to move step-by-step and give a chance to project teams to acclimatize 
with the changes I think starting with #2 should be sufficient.

Although if we think that option #1 is doable as a starting point and also end 
goal, you have my support for that too.

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

As being one of the advocates on having the documentation living together with 
the code so we can give a chance to the experts of the code changes to add the 
corresponding documentation as well, I'm definitely against option #3. :)

Thanks and Best Regards,
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

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

[Ildiko Vancsa]

> On 2017. May 23., at 15:43, Sean McGinnis  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 
>> 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.

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

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

[Anne Gentle]

On Tue, May 23, 2017 at 8:56 AM, Zane Bitter  wrote:

> On 22/05/17 05:39, Alexandra Settle wrote:
>
>> 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.
>>
>
> +0 in the short term, +1 for the long term
>
> 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.
>>
>
> +1, at least in the short term
>
> As we've been discussing since the summit, Heat has a bunch of
> documentation (specifically the Template Guide) that is end-user-facing but
> needs to be generated from the Heat repo (because it uses introspection on
> the code). Right now it's buried in the (OpenStack) developer-facing
> documentation, which is not very discoverable for end users. So generating
> the user guide from the project repos would allow us to move the Template
> Guide.


What prevents you from publishing to a different location? The landing page
or the URL or something else I'm not considering? The URL can be changed in
the publish job, I think, so what we really need are the "rules" and
organization. I already discovered at the PTG that we are not consistent
with version number and translation language in our URLs...

It's something we'll have to work on -- the usability of the landing pages
and the directories for the publish jobs and how those translate to URLs.
Thoughts?

Anne


>
>
> 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.
>>
>
> -1 for the reasons above.
>
> cheers,
> Zane.
>
>
> __
> 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
>



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
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

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

[Zane Bitter]

On 23/05/17 08:35, Alexandra Settle wrote:

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.


If it makes you feel better, I don't think this is specific to tech 
writers. There's a lot of (unjustified IMHO) fear in general about 
giving out core review rights to a subset of a repo when we don't have 
ACLs to enforce that.


Personally, I totally agree with you and John here - we already place a 
huge amount of trust in core reviewers. If we can't trust them to not 
randomly +2 stuff they don't understand then we have much, much bigger 
problems.


cheers,
Zane.

__
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

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

[Zane Bitter]

On 22/05/17 05:39, Alexandra Settle wrote:

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.


+0 in the short term, +1 for the long term


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.


+1, at least in the short term

As we've been discussing since the summit, Heat has a bunch of 
documentation (specifically the Template Guide) that is end-user-facing 
but needs to be generated from the Heat repo (because it uses 
introspection on the code). Right now it's buried in the (OpenStack) 
developer-facing documentation, which is not very discoverable for end 
users. So generating the user guide from the project repos would allow 
us to move the Template Guide.



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.


-1 for the reasons above.

cheers,
Zane.

__
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

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

[Sean McGinnis]

On Mon, May 22, 2017 at 05:50:50PM -0500, Anne Gentle wrote:
> On Mon, May 22, 2017 at 5:41 PM, Sean McGinnis 
> 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.

No specific experience to back this up, just the thought that someone coming
in could see a narrowly scoped repo and think "oh, that looks easy. I can help
with that." versus someone coming in to the whole project repo and getting
scared away because there's a bunch of things they don't understand and are
not sure where they can most easily jump in and contribute.

To be fair, I think all three options are good and could work.


__
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

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

[Alexandra Settle]

 
> 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

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

[Bogdan Dobrelya]

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 
>> wrote:
>>
>>> On Mon, May 22, 2017 at 09:39:09AM +, 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

__
OpenStack 

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

[John Dickinson]

On 22 May 2017, at 15:50, Anne Gentle wrote:

> On Mon, May 22, 2017 at 5:41 PM, Sean McGinnis 
> wrote:
>
>> On Mon, May 22, 2017 at 09:39:09AM +, 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-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
>>
>
>
>
> -- 
>
> Read my blog: justwrite.click 

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

[Anne Gentle]

On Mon, May 22, 2017 at 5:41 PM, Sean McGinnis 
wrote:

> On Mon, May 22, 2017 at 09:39:09AM +, 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


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



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
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

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

[Sean McGinnis]

On Mon, May 22, 2017 at 09:39:09AM +, 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.

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

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

[Doug Hellmann]

Excerpts from Anne Gentle's message of 2017-05-22 12:36:29 -0500:
> > On May 22, 2017, at 9:09 AM, Doug Hellmann  wrote:
> >
> > Excerpts from Dmitry Tantsur's message of 2017-05-22 12:26:25 +0200:
> >>> On 05/22/2017 11:39 AM, Alexandra Settle wrote:
> >>> Hi everyone,
> >>>
> >>> The documentation team are rapidly losing key contributors and core 
> >>> reviewers.
> >>> We are not alone, this is happening across the board. It is making things
> >>> harder, but not impossible.
> >>>
> >>> Since our inception in 2010, we’ve been climbing higher and higher trying 
> >>> to
> >>> achieve the best documentation we could, and uphold our high standards. 
> >>> This is
> >>> something to be incredibly proud of.
> >>>
> >>> However, we now need to take a step back and realise that the amount of 
> >>> work we
> >>> are attempting to maintain is now out of reach for the team size that we 
> >>> have.
> >>> At the moment we have 13 cores, of whom none are full time contributors or
> >>> reviewers. This includes myself.
> >>>
> >>> Until this point, the documentation team has owned several manuals that 
> >>> include
> >>> content related to multiple projects, including an installation guide, 
> >>> admin
> >>> guide, configuration guide, networking guide, and security guide. Because 
> >>> the
> >>> team no longer has the resources to own that content, we want to invert 
> >>> the
> >>> relationship between the doc team and project teams, so that we become 
> >>> liaisons
> >>> to help with maintenance instead of asking for project teams to provide 
> >>> liaisons
> >>> to help with content. As a part of that change, we plan to move the 
> >>> existing
> >>> content out of the central manuals repository, into repositories owned by 
> >>> the
> >>> appropriate project teams. Project teams will then own the content and the
> >>> documentation team will assist by managing the build tools, helping with 
> >>> writing
> >>> guidelines and style, but not writing the bulk of the text.
> >>>
> >>> We currently have the infrastructure set up to empower project teams to 
> >>> manage
> >>> their own documentation in their own tree, and many do. As part of this 
> >>> change,
> >>> the rest of the existing content from the install guide and admin guide 
> >>> will
> >>> also move into project-owned repositories. We have a few options for how 
> >>> to
> >>> implement the move, and that's where we need feedback now.
> >>>
> >>> 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.
> >>>
> >>> 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?
> >>
> >> We're already hosting install-guide and api-ref in our tree, and I'd 
> >> prefer we
> >> don't change it, as it's going to be annoying (especially wrt backports). 
> 

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

[Doug Hellmann]

Excerpts from Michał Jastrzębski's message of 2017-05-22 10:42:44 -0700:
> [snip]
> 
> So from Kolla perspective, since our dev guide is really also
> operators guide (we are operators tool so we're kinda "special" on
> that front), we'd love to handle both deployment guide, user manuals
> and all that in our tree. If we could create infrastructure that would
> allow us to segregate our content and manage it ourselves, I think
> that would be useful. Tell us how to help:)
> 
> Cheers,
> Michal
> 

The first step is to choose one of the options Alex proposed. From
there, we'll work out more detailed steps for achieving that.

Doug

__
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

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

[Michał Jastrzębski]

[snip]

So from Kolla perspective, since our dev guide is really also
operators guide (we are operators tool so we're kinda "special" on
that front), we'd love to handle both deployment guide, user manuals
and all that in our tree. If we could create infrastructure that would
allow us to segregate our content and manage it ourselves, I think
that would be useful. Tell us how to help:)

Cheers,
Michal

__
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

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

[Anne Gentle]

> On May 22, 2017, at 9:09 AM, Doug Hellmann  wrote:
>
> Excerpts from Dmitry Tantsur's message of 2017-05-22 12:26:25 +0200:
>>> On 05/22/2017 11:39 AM, Alexandra Settle wrote:
>>> Hi everyone,
>>>
>>> The documentation team are rapidly losing key contributors and core 
>>> reviewers.
>>> We are not alone, this is happening across the board. It is making things
>>> harder, but not impossible.
>>>
>>> Since our inception in 2010, we’ve been climbing higher and higher trying to
>>> achieve the best documentation we could, and uphold our high standards. 
>>> This is
>>> something to be incredibly proud of.
>>>
>>> However, we now need to take a step back and realise that the amount of 
>>> work we
>>> are attempting to maintain is now out of reach for the team size that we 
>>> have.
>>> At the moment we have 13 cores, of whom none are full time contributors or
>>> reviewers. This includes myself.
>>>
>>> Until this point, the documentation team has owned several manuals that 
>>> include
>>> content related to multiple projects, including an installation guide, admin
>>> guide, configuration guide, networking guide, and security guide. Because 
>>> the
>>> team no longer has the resources to own that content, we want to invert the
>>> relationship between the doc team and project teams, so that we become 
>>> liaisons
>>> to help with maintenance instead of asking for project teams to provide 
>>> liaisons
>>> to help with content. As a part of that change, we plan to move the existing
>>> content out of the central manuals repository, into repositories owned by 
>>> the
>>> appropriate project teams. Project teams will then own the content and the
>>> documentation team will assist by managing the build tools, helping with 
>>> writing
>>> guidelines and style, but not writing the bulk of the text.
>>>
>>> We currently have the infrastructure set up to empower project teams to 
>>> manage
>>> their own documentation in their own tree, and many do. As part of this 
>>> change,
>>> the rest of the existing content from the install guide and admin guide will
>>> also move into project-owned repositories. We have a few options for how to
>>> implement the move, and that's where we need feedback now.
>>>
>>> 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.
>>>
>>> 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?
>>
>> We're already hosting install-guide and api-ref in our tree, and I'd prefer 
>> we
>> don't change it, as it's going to be annoying (especially wrt backports). I'd
>> prefer we create user-guide directory in projects, and move the user guide 
>> there.
>
> Handling backports with a merged guide is an issue we didn't come
> up with in our earlier discussions. How often do you backport doc
> changes in practice? Do you foresee merge conflicts caused by issues
> other than the files being renamed?
>

For 

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

[Doug Hellmann]

Excerpts from Dmitry Tantsur's message of 2017-05-22 16:54:30 +0200:
> On 05/22/2017 04:09 PM, Doug Hellmann wrote:
> > Excerpts from Dmitry Tantsur's message of 2017-05-22 12:26:25 +0200:
> >> On 05/22/2017 11:39 AM, Alexandra Settle wrote:
> >>> Hi everyone,
> >>>
> >>> The documentation team are rapidly losing key contributors and core 
> >>> reviewers.
> >>> We are not alone, this is happening across the board. It is making things
> >>> harder, but not impossible.
> >>>
> >>> Since our inception in 2010, we’ve been climbing higher and higher trying 
> >>> to
> >>> achieve the best documentation we could, and uphold our high standards. 
> >>> This is
> >>> something to be incredibly proud of.
> >>>
> >>> However, we now need to take a step back and realise that the amount of 
> >>> work we
> >>> are attempting to maintain is now out of reach for the team size that we 
> >>> have.
> >>> At the moment we have 13 cores, of whom none are full time contributors or
> >>> reviewers. This includes myself.
> >>>
> >>> Until this point, the documentation team has owned several manuals that 
> >>> include
> >>> content related to multiple projects, including an installation guide, 
> >>> admin
> >>> guide, configuration guide, networking guide, and security guide. Because 
> >>> the
> >>> team no longer has the resources to own that content, we want to invert 
> >>> the
> >>> relationship between the doc team and project teams, so that we become 
> >>> liaisons
> >>> to help with maintenance instead of asking for project teams to provide 
> >>> liaisons
> >>> to help with content. As a part of that change, we plan to move the 
> >>> existing
> >>> content out of the central manuals repository, into repositories owned by 
> >>> the
> >>> appropriate project teams. Project teams will then own the content and the
> >>> documentation team will assist by managing the build tools, helping with 
> >>> writing
> >>> guidelines and style, but not writing the bulk of the text.
> >>>
> >>> We currently have the infrastructure set up to empower project teams to 
> >>> manage
> >>> their own documentation in their own tree, and many do. As part of this 
> >>> change,
> >>> the rest of the existing content from the install guide and admin guide 
> >>> will
> >>> also move into project-owned repositories. We have a few options for how 
> >>> to
> >>> implement the move, and that's where we need feedback now.
> >>>
> >>> 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.
> >>>
> >>> 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?
> >>
> >> We're already hosting install-guide and api-ref in our tree, and I'd 
> >> prefer we
> >> don't change it, as it's going to be annoying (especially wrt backports). 
> >> I'd
> >> prefer we create 

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

[Dmitry Tantsur]

On 05/22/2017 04:09 PM, Doug Hellmann wrote:

Excerpts from Dmitry Tantsur's message of 2017-05-22 12:26:25 +0200:

On 05/22/2017 11:39 AM, Alexandra Settle wrote:

Hi everyone,

The documentation team are rapidly losing key contributors and core reviewers.
We are not alone, this is happening across the board. It is making things
harder, but not impossible.

Since our inception in 2010, we’ve been climbing higher and higher trying to
achieve the best documentation we could, and uphold our high standards. This is
something to be incredibly proud of.

However, we now need to take a step back and realise that the amount of work we
are attempting to maintain is now out of reach for the team size that we have.
At the moment we have 13 cores, of whom none are full time contributors or
reviewers. This includes myself.

Until this point, the documentation team has owned several manuals that include
content related to multiple projects, including an installation guide, admin
guide, configuration guide, networking guide, and security guide. Because the
team no longer has the resources to own that content, we want to invert the
relationship between the doc team and project teams, so that we become liaisons
to help with maintenance instead of asking for project teams to provide liaisons
to help with content. As a part of that change, we plan to move the existing
content out of the central manuals repository, into repositories owned by the
appropriate project teams. Project teams will then own the content and the
documentation team will assist by managing the build tools, helping with writing
guidelines and style, but not writing the bulk of the text.

We currently have the infrastructure set up to empower project teams to manage
their own documentation in their own tree, and many do. As part of this change,
the rest of the existing content from the install guide and admin guide will
also move into project-owned repositories. We have a few options for how to
implement the move, and that's where we need feedback now.

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.

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?


We're already hosting install-guide and api-ref in our tree, and I'd prefer we
don't change it, as it's going to be annoying (especially wrt backports). I'd
prefer we create user-guide directory in projects, and move the user guide 
there.


Handling backports with a merged guide is an issue we didn't come
up with in our earlier discussions. How often do you backport doc
changes in practice? Do you foresee merge conflicts caused by issues
other than the files being renamed?


When we created our in-tree install-guide, we backported the whole of it to the 
previous release :)


But mostly, I expect that if a bug fix requires a change to install-guide (the 
bug is in install-guide itself, or we need to document a know issue, or 
anything), it has to be backportable.


Files being renamed can already be an issue (sometimes git suddenly chokes on 
them). Anyway, currently we're in process of refactoring our install-guide, so 

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

[Doug Hellmann]

Excerpts from Anne Gentle's message of 2017-05-22 08:08:40 -0500:
> On Mon, May 22, 2017 at 4:39 AM, Alexandra Settle 
> wrote:
> 
> > Hi everyone,
> >
> >
> >
> > The documentation team are rapidly losing key contributors and core
> > reviewers. We are not alone, this is happening across the board. It is
> > making things harder, but not impossible.
> >
> > Since our inception in 2010, we’ve been climbing higher and higher trying
> > to achieve the best documentation we could, and uphold our high standards.
> > This is something to be incredibly proud of.
> >
> >
> >
> > However, we now need to take a step back and realise that the amount of
> > work we are attempting to maintain is now out of reach for the team size
> > that we have. At the moment we have 13 cores, of whom none are full time
> > contributors or reviewers. This includes myself.
> >
> 
> One point I'd like to emphasize with this proposal, any way we go, is that
> we would prefer that the writing tasks not always fall on the devs, but
> that there can be dedicated writers or ops or end-users attending to info
> needs, it's just that they'll do the work in the repos.

I'm not sure we can assume that will be the case. If we have writers,
obviously we want their help here. But if we have no dedicated writers,
we need project teams to take more responsibility for the docs for what
they produce.

> Also, I'm working on a patch to try to quantify the best practices using
> our current data: https://review.openstack.org/#/c/461280/ We may discover
> some ways to work that mean gaining efficiencies and ensuring quality.
> Project teams should consider changes to reviewers and so on to try to be
> inclusive of the varied types of work in their repo.
> 
> I'll emphasize that we need to be extremely protective of the user space
> with this sort of move. No one who reads the docs ultimately cares about
> how they are put together. They just want to find what they need and get on
> with their lives.

For me, this is another point in favor of option 2, which involves
the least amount of disruption to existing publishing jobs (affecting
contributors) and locations (affecting consumers).  Once we transfer
ownership and have the builds working, we can discuss more significant
changes.

> > Until this point, the documentation team has owned several manuals that
> > include content related to multiple projects, including an installation
> > guide, admin guide, configuration guide, networking guide, and security
> > guide. Because the team no longer has the resources to own that content, we
> > want to invert the relationship between the doc team and project teams, so
> > that we become liaisons to help with maintenance instead of asking for
> > project teams to provide liaisons to help with content. As a part of that
> > change, we plan to move the existing content out of the central manuals
> > repository, into repositories owned by the appropriate project teams.
> > Project teams will then own the content and the documentation team will
> > assist by managing the build tools, helping with writing guidelines
> > and style, but not writing the bulk of the text.
> >
> >
> >
> > We currently have the infrastructure set up to empower project teams to
> > manage their own documentation in their own tree, and many do. As part of
> > this change, the rest of the existing content from the install guide and
> > admin guide will also move into project-owned repositories. We have a few
> > options for how to implement the move, and that's where we need feedback
> > now.
> >
> >
> >
> > 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.
> >
> 
> I'd love to try this one. I know this is what John Dickenson has tried for
> the swift project with https://review.openstack.org/#/c/386834/ but since
> it didn't match anyone else, and I haven't heard back yet about the user
> experience, we didn't pursue much.
> 
> I'll still be pretty adamant about the user experience, so that the project
> name does not spill over into the user space. Redirects will be crucial as
> someone pointed out in one of the recent etherpads. Also, it may require
> not publishing api-ref info to developer.openstack.org (in other words, one
> job means one target for publication right now).
> 
> >
> >
> > 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, 

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

[Doug Hellmann]

Excerpts from Dmitry Tantsur's message of 2017-05-22 12:26:25 +0200:
> On 05/22/2017 11:39 AM, Alexandra Settle wrote:
> > Hi everyone,
> > 
> > The documentation team are rapidly losing key contributors and core 
> > reviewers. 
> > We are not alone, this is happening across the board. It is making things 
> > harder, but not impossible.
> > 
> > Since our inception in 2010, we’ve been climbing higher and higher trying 
> > to 
> > achieve the best documentation we could, and uphold our high standards. 
> > This is 
> > something to be incredibly proud of.
> > 
> > However, we now need to take a step back and realise that the amount of 
> > work we 
> > are attempting to maintain is now out of reach for the team size that we 
> > have. 
> > At the moment we have 13 cores, of whom none are full time contributors or 
> > reviewers. This includes myself.
> > 
> > Until this point, the documentation team has owned several manuals that 
> > include 
> > content related to multiple projects, including an installation guide, 
> > admin 
> > guide, configuration guide, networking guide, and security guide. Because 
> > the 
> > team no longer has the resources to own that content, we want to invert the 
> > relationship between the doc team and project teams, so that we become 
> > liaisons 
> > to help with maintenance instead of asking for project teams to provide 
> > liaisons 
> > to help with content. As a part of that change, we plan to move the 
> > existing 
> > content out of the central manuals repository, into repositories owned by 
> > the 
> > appropriate project teams. Project teams will then own the content and the 
> > documentation team will assist by managing the build tools, helping with 
> > writing 
> > guidelines and style, but not writing the bulk of the text.
> > 
> > We currently have the infrastructure set up to empower project teams to 
> > manage 
> > their own documentation in their own tree, and many do. As part of this 
> > change, 
> > the rest of the existing content from the install guide and admin guide 
> > will 
> > also move into project-owned repositories. We have a few options for how to 
> > implement the move, and that's where we need feedback now.
> > 
> > 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.
> > 
> > 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?
> 
> We're already hosting install-guide and api-ref in our tree, and I'd prefer 
> we 
> don't change it, as it's going to be annoying (especially wrt backports). I'd 
> prefer we create user-guide directory in projects, and move the user guide 
> there.

Handling backports with a merged guide is an issue we didn't come
up with in our earlier discussions. How often do you backport doc
changes in practice? Do you foresee merge conflicts caused by issues
other than the files being renamed?

Doug

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

[Anne Gentle]

On Mon, May 22, 2017 at 4:39 AM, Alexandra Settle 
wrote:

> Hi everyone,
>
>
>
> The documentation team are rapidly losing key contributors and core
> reviewers. We are not alone, this is happening across the board. It is
> making things harder, but not impossible.
>
> Since our inception in 2010, we’ve been climbing higher and higher trying
> to achieve the best documentation we could, and uphold our high standards.
> This is something to be incredibly proud of.
>
>
>
> However, we now need to take a step back and realise that the amount of
> work we are attempting to maintain is now out of reach for the team size
> that we have. At the moment we have 13 cores, of whom none are full time
> contributors or reviewers. This includes myself.
>

One point I'd like to emphasize with this proposal, any way we go, is that
we would prefer that the writing tasks not always fall on the devs, but
that there can be dedicated writers or ops or end-users attending to info
needs, it's just that they'll do the work in the repos.

Also, I'm working on a patch to try to quantify the best practices using
our current data: https://review.openstack.org/#/c/461280/ We may discover
some ways to work that mean gaining efficiencies and ensuring quality.
Project teams should consider changes to reviewers and so on to try to be
inclusive of the varied types of work in their repo.

I'll emphasize that we need to be extremely protective of the user space
with this sort of move. No one who reads the docs ultimately cares about
how they are put together. They just want to find what they need and get on
with their lives.


>
>
> Until this point, the documentation team has owned several manuals that
> include content related to multiple projects, including an installation
> guide, admin guide, configuration guide, networking guide, and security
> guide. Because the team no longer has the resources to own that content, we
> want to invert the relationship between the doc team and project teams, so
> that we become liaisons to help with maintenance instead of asking for
> project teams to provide liaisons to help with content. As a part of that
> change, we plan to move the existing content out of the central manuals
> repository, into repositories owned by the appropriate project teams.
> Project teams will then own the content and the documentation team will
> assist by managing the build tools, helping with writing guidelines
> and style, but not writing the bulk of the text.
>
>
>
> We currently have the infrastructure set up to empower project teams to
> manage their own documentation in their own tree, and many do. As part of
> this change, the rest of the existing content from the install guide and
> admin guide will also move into project-owned repositories. We have a few
> options for how to implement the move, and that's where we need feedback
> now.
>
>
>
> 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.
>

I'd love to try this one. I know this is what John Dickenson has tried for
the swift project with https://review.openstack.org/#/c/386834/ but since
it didn't match anyone else, and I haven't heard back yet about the user
experience, we didn't pursue much.

I'll still be pretty adamant about the user experience, so that the project
name does not spill over into the user space. Redirects will be crucial as
someone pointed out in one of the recent etherpads. Also, it may require
not publishing api-ref info to developer.openstack.org (in other words, one
job means one target for publication right now).


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

It's possible the data could point us in 

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

[Dmitry Tantsur]

On 05/22/2017 11:39 AM, Alexandra Settle wrote:

Hi everyone,

The documentation team are rapidly losing key contributors and core reviewers. 
We are not alone, this is happening across the board. It is making things 
harder, but not impossible.


Since our inception in 2010, we’ve been climbing higher and higher trying to 
achieve the best documentation we could, and uphold our high standards. This is 
something to be incredibly proud of.


However, we now need to take a step back and realise that the amount of work we 
are attempting to maintain is now out of reach for the team size that we have. 
At the moment we have 13 cores, of whom none are full time contributors or 
reviewers. This includes myself.


Until this point, the documentation team has owned several manuals that include 
content related to multiple projects, including an installation guide, admin 
guide, configuration guide, networking guide, and security guide. Because the 
team no longer has the resources to own that content, we want to invert the 
relationship between the doc team and project teams, so that we become liaisons 
to help with maintenance instead of asking for project teams to provide liaisons 
to help with content. As a part of that change, we plan to move the existing 
content out of the central manuals repository, into repositories owned by the 
appropriate project teams. Project teams will then own the content and the 
documentation team will assist by managing the build tools, helping with writing 
guidelines and style, but not writing the bulk of the text.


We currently have the infrastructure set up to empower project teams to manage 
their own documentation in their own tree, and many do. As part of this change, 
the rest of the existing content from the install guide and admin guide will 
also move into project-owned repositories. We have a few options for how to 
implement the move, and that's where we need feedback now.


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.


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?


We're already hosting install-guide and api-ref in our tree, and I'd prefer we 
don't change it, as it's going to be annoying (especially wrt backports). I'd 
prefer we create user-guide directory in projects, and move the user guide there.




Cheers,

Alex



__
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-dev] [doc][ptls][all] Documentation publishing future

[Alexandra Settle]

Hi everyone,

The documentation team are rapidly losing key contributors and core reviewers. 
We are not alone, this is happening across the board. It is making things 
harder, but not impossible.
Since our inception in 2010, we’ve been climbing higher and higher trying to 
achieve the best documentation we could, and uphold our high standards. This is 
something to be incredibly proud of.

However, we now need to take a step back and realise that the amount of work we 
are attempting to maintain is now out of reach for the team size that we have. 
At the moment we have 13 cores, of whom none are full time contributors or 
reviewers. This includes myself.

Until this point, the documentation team has owned several manuals that include 
content related to multiple projects, including an installation guide, admin 
guide, configuration guide, networking guide, and security guide. Because the 
team no longer has the resources to own that content, we want to invert the 
relationship between the doc team and project teams, so that we become liaisons 
to help with maintenance instead of asking for project teams to provide 
liaisons to help with content. As a part of that change, we plan to move the 
existing content out of the central manuals repository, into repositories owned 
by the appropriate project teams. Project teams will then own the content and 
the documentation team will assist by managing the build tools, helping with 
writing guidelines and style, but not writing the bulk of the text.

We currently have the infrastructure set up to empower project teams to manage 
their own documentation in their own tree, and many do. As part of this change, 
the rest of the existing content from the install guide and admin guide will 
also move into project-owned repositories. We have a few options for how to 
implement the move, and that's where we need feedback now.

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.

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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev