[all] [tc] [docs] [release] [ptls] Docs as SIG: Ownership of docs.openstack.org
Hi all,
Quick recap: The documentation team is set to disband as an official project, and make the leap to becoming a SIG (Special Interest Group).
This decision is not one we have made lightly, but with the changes of direction since Pike (project documentation belonging with the projects, etc) the need for a centralised documentation team as an official project is no longer integral to producing the software.
The transition of the docs team to a SIG has already begun [1] and [2]. The openstackdocstheme, openstack-doc-tools, os-api-ref and whereto have been placed within the remit of the Oslo team and approved.
The remaining individuals working on the docs team are sorting through what's left and where it is best placed. In [1], Doug has rightfully pointed out that whilst the documentation team as it stands today is no longer "integral", the docs.openstack.org web site is. An owner is required.
The suggestion is for the Release Management team is the "least worst" (thanks, tonyb) place for the website manaagement to land. As Tony points out, this requires learning new tools and processes but the individuals working on the docs team currently have no intention to leave, and are around to help manage this from the SIG.
Open to discussion and suggestions, but to summarise the proposal here:
docs.openstack.org ownership is to transition to be the responsibility of the Release Management team officially provided there are no strong objections.
Thanks,
Alex IRC: asettle
[1] https://review.opendev.org/#/c/657142/ [2] https://review.opendev.org/#/c/657141/
On 2019-08-19 13:17:35 +0000 (+0000), Alexandra Settle wrote: [...]
Doug has rightfully pointed out that whilst the documentation team as it stands today is no longer "integral", the docs.openstack.org web site is. An owner is required.
The suggestion is for the Release Management team is the "least worst" (thanks, tonyb) place for the website manaagement to land. As Tony points out, this requires learning new tools and processes but the individuals working on the docs team currently have no intention to leave, and are around to help manage this from the SIG.
Open to discussion and suggestions, but to summarise the proposal here:
docs.openstack.org ownership is to transition to be the responsibility of the Release Management team officially provided there are no strong objections.
[...]
The prose above is rather vague on what "the docs.openstack.org web site" entails. Inferring from Doug's comments on 657142, I think you and he are referring specifically to the content in the https://opendev.org/openstack/openstack-manuals/src/branch/master/www subtree. Is that pretty much it? The Apache virtual host configuration and filesystem hosting the site itself are managed by the Infra/OpenDev team, and there aren't any plans to change that as far as I'm aware.
On Aug 19, 2019, at 10:59 AM, Jeremy Stanley fungi@yuggoth.org wrote:
On 2019-08-19 13:17:35 +0000 (+0000), Alexandra Settle wrote: [...]
Doug has rightfully pointed out that whilst the documentation team as it stands today is no longer "integral", the docs.openstack.org web site is. An owner is required.
The suggestion is for the Release Management team is the "least worst" (thanks, tonyb) place for the website manaagement to land. As Tony points out, this requires learning new tools and processes but the individuals working on the docs team currently have no intention to leave, and are around to help manage this from the SIG.
Open to discussion and suggestions, but to summarise the proposal here:
docs.openstack.org ownership is to transition to be the responsibility of the Release Management team officially provided there are no strong objections.
[...]
The prose above is rather vague on what "the docs.openstack.org web site" entails. Inferring from Doug's comments on 657142, I think you and he are referring specifically to the content in the https://opendev.org/openstack/openstack-manuals/src/branch/master/www subtree. Is that pretty much it? The Apache virtual host configuration and filesystem hosting the site itself are managed by the Infra/OpenDev team, and there aren't any plans to change that as far as I'm aware. -- Jeremy Stanley
Yes, that’s correct.
Doug
Quick recap: The documentation team is set to disband as an official project, and make the leap to becoming a SIG (Special Interest Group).
The remaining individuals working on the docs team are sorting through what's left and where it is best placed. In [1], Doug has rightfully pointed out that whilst the documentation team as it stands today is no longer "integral", the docs.openstack.org web site is. An owner is required.
Unless things have changed, SIGs can be owners of a resource published via docs.openstack.org (and I am assuming that means be extension, docs.o.o itself). Is there a reason the Docs SIG would not still be able to own the site?
The suggestion is for the Release Management team is the "least worst" (thanks, tonyb) place for the website manaagement to land. As Tony points out, this requires learning new tools and processes but the individuals working on the docs team currently have no intention to leave, and are around to help manage this from the SIG.
I'm personally fine with the release team taking this on, but it does seem like an odd fit. I think it would make a lot more sense for the Docs SIG to own the docs site than the release team.
Open to discussion and suggestions, but to summarise the proposal here:
docs.openstack.org ownership is to transition to be the responsibility of the Release Management team officially provided there are no strong objections.
Thanks,
Alex IRC: asettle
[1] https://review.opendev.org/#/c/657142/ [2] https://review.opendev.org/#/c/657141/
On Aug 19, 2019, at 11:41 AM, Sean McGinnis sean.mcginnis@gmx.com wrote:
Quick recap: The documentation team is set to disband as an official project, and make the leap to becoming a SIG (Special Interest Group).
The remaining individuals working on the docs team are sorting through what's left and where it is best placed. In [1], Doug has rightfully pointed out that whilst the documentation team as it stands today is no longer "integral", the docs.openstack.org web site is. An owner is required.
Unless things have changed, SIGs can be owners of a resource published via docs.openstack.org (and I am assuming that means be extension, docs.o.o itself). Is there a reason the Docs SIG would not still be able to own the site?
The suggestion is for the Release Management team is the "least worst" (thanks, tonyb) place for the website manaagement to land. As Tony points out, this requires learning new tools and processes but the individuals working on the docs team currently have no intention to leave, and are around to help manage this from the SIG.
I'm personally fine with the release team taking this on, but it does seem like an odd fit. I think it would make a lot more sense for the Docs SIG to own the docs site than the release team.
Thierry has always drawn (one of) the distinction(s) between teams and SIGs as being that teams own tasks that are “part of” the thing we produce that we call OpenStack, while SIGs are less formally part of that input to that production process.
Updating the docs site every time we have a new release felt like it should be part of the formal process, and definitely not something we should leave to chance. The cadence made me think the release team could be a good home.
It’s 95% automated now, for what that’s worth. I imagine someone could automate the step of adding the new series pages, although I’m not sure what the trigger would be.
We could also look at other ways to build the site that don’t require any action each cycle, of course, including not updating it at all and only publishing docs out of master. That’s especially appealing if we don’t have anyone in the community willing and able to pick up the work.
Open to discussion and suggestions, but to summarise the proposal here:
docs.openstack.org ownership is to transition to be the responsibility of the Release Management team officially provided there are no strong objections.
Thanks,
Alex IRC: asettle
[1] https://review.opendev.org/#/c/657142/ [2] https://review.opendev.org/#/c/657141/
The suggestion is for the Release Management team is the "least worst" (thanks, tonyb) place for the website manaagement to land. As Tony points out, this requires learning new tools and processes but the individuals working on the docs team currently have no intention to leave, and are around to help manage this from the SIG.
I'm personally fine with the release team taking this on, but it does seem like an odd fit. I think it would make a lot more sense for the Docs SIG to own the docs site than the release team.
Thierry has always drawn (one of) the distinction(s) between teams and SIGs as being that teams own tasks that are “part of” the thing we produce that we call OpenStack, while SIGs are less formally part of that input to that production process.
Updating the docs site every time we have a new release felt like it should be part of the formal process, and definitely not something we should leave to chance. The cadence made me think the release team could be a good home.
It’s 95% automated now, for what that’s worth. I imagine someone could automate the step of adding the new series pages, although I’m not sure what the trigger would be.
We could also look at other ways to build the site that don’t require any action each cycle, of course, including not updating it at all and only publishing docs out of master. That’s especially appealing if we don’t have anyone in the community willing and able to pick up the work.
This is a little different scope though, isn't it? Maybe I misunderstood the original proposal, but to me there seems to be a big difference between owning the task of configuring the site for the next release (which totally makes sense as a release team task) and owning the entire docs.openstack.org site.
On 2019-08-19 12:49:41 -0500 (-0500), Sean McGinnis wrote: [...]
there seems to be a big difference between owning the task of configuring the site for the next release (which totally makes sense as a release team task) and owning the entire docs.openstack.org site.
That's why I also requested clarification in my earlier message on this thread. The vast majority of the content hosted under https://docs.openstack.org/ is maintained in a distributed fashion by the various teams writing documentation in their respective projects. The hosting (configuration apart from .htaccess files, storage, DNS, and so on) is handled by Infra/OpenDev folks. If it's *just* the stuff inside the "www" tree in the openstack-manuals repo then that's not a lot, but it's also possible what the release team actually needs to touch in there could be successfully scaled back even more (with the caveat that I haven't looked through it in detail).
On 2019-08-19 17:56:53 +0000 (+0000), Jeremy Stanley wrote: [...]
The vast majority of the content hosted under https://docs.openstack.org/ is maintained in a distributed fashion by the various teams writing documentation in their respective projects. The hosting (configuration apart from .htaccess files, storage, DNS, and so on) is handled by Infra/OpenDev folks.
[...]
Oh, and let's not forget the publication automation/jobs for the site, which are also presumably not part of the scope of what's being discussed as becoming the release team's direct responsibility. Those are already overseen by job configuration reviewers for the project-config and openstack-zuul-jobs repositories.
On Aug 19, 2019, at 1:56 PM, Jeremy Stanley fungi@yuggoth.org wrote:
On 2019-08-19 12:49:41 -0500 (-0500), Sean McGinnis wrote: [...]
there seems to be a big difference between owning the task of configuring the site for the next release (which totally makes sense as a release team task) and owning the entire docs.openstack.org site.
That's why I also requested clarification in my earlier message on this thread. The vast majority of the content hosted under https://docs.openstack.org/ is maintained in a distributed fashion by the various teams writing documentation in their respective projects. The hosting (configuration apart from .htaccess files, storage, DNS, and so on) is handled by Infra/OpenDev folks. If it's *just* the stuff inside the "www" tree in the openstack-manuals repo then that's not a lot, but it's also possible what the release team actually needs to touch in there could be successfully scaled back even more (with the caveat that I haven't looked through it in detail). -- Jeremy Stanley
The suggestion is for the release team to take over the site generator for docs.openstack.org (the stuff under “www” in the current openstack-manuals git repository) and for the SIG to own anything that looks remotely like “content”. There isn’t much of that left anyway, now that most of it is in the project repositories.
Most of what is under www is series-specific templates and data files that tell the site generator how to insert links to parts of the project documentation in the right places (the “install guides” page links to /foo/$series/install/ for example). They’re very simple, very dumb, templates, driven with a little custom script that wraps jinja2, feeding the right data to the right templates based on series name. There is pretty good documentation for how to use it in the tools [1] and release [2] sections of the docs contributor guide.
The current site-generator definitely could be simpler, especially if it only linked to the master docs and *those* linked to the older versions of themselves (so /nova/latest/ had a link that pointed to /nova/ocata/ somewhere). That would take some work, though.
The simplest thing we could do is just make the release team committers on openstack-manuals, leave everything else as it is, and exercise trust between the two groups. If we absolutely want to separate the builds, then we could make a new repo with just the template-driven pages under “www”, but that’s going to involve changing/creating several publishing jobs.
Doug
[1] https://docs.openstack.org/doc-contrib-guide/doc-tools.html [2] https://docs.openstack.org/doc-contrib-guide/release.html
Doug Hellmann wrote:
On 2019-08-19 12:49:41 -0500 (-0500), Sean McGinnis wrote: [...]
there seems to be a big difference between owning the task of configuring the site for the next release (which totally makes sense as a release team task) and owning the entire docs.openstack.org site.
The suggestion is for the release team to take over the site generator for docs.openstack.org (the stuff under “www” in the current openstack-manuals git repository) and for the SIG to own anything that looks remotely like “content”. There isn’t much of that left anyway, now that most of it is in the project repositories.
Yes, my understanding was that the release team would only own the site generation and associated cycle-tied mechanics. I felt like that was akin to "releasing the docs" (whatever they end up containing), and at this point docs are just a specific form of project team deliverable. We have to care for those things getting done as part of the release cycle anyway.
It's not a great fit, but it's probably not the worst either. And there aren't that many alternatives solutions (the TC would arguably be a worse fit).
Yes, my understanding was that the release team would only own the site generation and associated cycle-tied mechanics. I felt like that was akin to "releasing the docs" (whatever they end up containing), and at this point docs are just a specific form of project team deliverable.
+1 that's how I see it too
We have to care for those things getting done as part of the release cycle anyway.
It's not a great fit, but it's probably not the worst either. And there aren't that many alternatives solutions (the TC would arguably be a worse fit).
On another note, the transition of docs to a SIG means we need to thoroughly define what a SIG is. JP and I discussed this offline, and provided our thoughts on Rico's creating the comparison of offical group structures document [1]. At this point in time, I see the definition as being too vague to truly be able to adopt docs and other projects that may inevitably want to do the same thing.
Discussion is welcomed on the patch.
[1] https://review.opendev.org/#/c/668093/
Dragging this thread back up from the depths as I've updated the governance patch as of this morning: https://review.opendev.org/#/c/657 142/
On Mon, 2019-08-19 at 14:16 -0400, Doug Hellmann wrote:
On Aug 19, 2019, at 1:56 PM, Jeremy Stanley fungi@yuggoth.org wrote:
On 2019-08-19 12:49:41 -0500 (-0500), Sean McGinnis wrote: [...]
there seems to be a big difference between owning the task of configuring the site for the next release (which totally makes sense as a release team task) and owning the entire docs.openstack.org site.
That's why I also requested clarification in my earlier message on this thread. The vast majority of the content hosted under https://docs.openstack.org/ is maintained in a distributed fashion by the various teams writing documentation in their respective projects. The hosting (configuration apart from .htaccess files, storage, DNS, and so on) is handled by Infra/OpenDev folks. If it's *just* the stuff inside the "www" tree in the openstack-manuals repo then that's not a lot, but it's also possible what the release team actually needs to touch in there could be successfully scaled back even more (with the caveat that I haven't looked through it in detail). -- Jeremy Stanley
The suggestion is for the release team to take over the site generator for docs.openstack.org (the stuff under “www” in the current openstack-manuals git repository) and for the SIG to own anything that looks remotely like “content”. There isn’t much of that left anyway, now that most of it is in the project repositories.
I like this.
Most of what is under www is series-specific templates and data files that tell the site generator how to insert links to parts of the project documentation in the right places (the “install guides” page links to /foo/$series/install/ for example). They’re very simple, very dumb, templates, driven with a little custom script that wraps jinja2, feeding the right data to the right templates based on series name. There is pretty good documentation for how to use it in the tools [1] and release [2] sections of the docs contributor guide.
The current site-generator definitely could be simpler, especially if it only linked to the master docs and *those* linked to the older versions of themselves (so /nova/latest/ had a link that pointed to /nova/ocata/ somewhere). That would take some work, though.
The simplest thing we could do is just make the release team committers on openstack-manuals, leave everything else as it is, and exercise trust between the two groups. If we absolutely want to separate the builds, then we could make a new repo with just the template-driven pages under “www”, but that’s going to involve changing/creating several publishing jobs.
I think this is a suitable option. I would like the docs team cores to review this, and approve. But I think this is the best/simpliest option for now.
participants (5)
-
Alexandra Settle
-
Doug Hellmann
-
Jeremy Stanley
-
Sean McGinnis
-
Thierry Carrez