Re: [openstack-dev] [docs] Nominating Ian Y. Choi for openstack-doc-core

[Petr Kovar]

On Sat, 22 Sep 2018 23:32:06 +0900
"Ian Y. Choi"  wrote:

> Thanks a lot all for such nomination & agreement!
> 
> I would like to do my best after I become doc-core as like what I 
> current do,
> although I still need the help from so many kind, energetic, and 
> enthusiastic OpenStack contributors and core members
> on OpenStack documentation and so many projects.

Thank you, Ian. Just updated the perms, congrats on your new role!

Best,
pk
 

> Melvin Hillsman wrote on 9/21/2018 5:31 AM:
> > ++
> >
> > On Thu, Sep 20, 2018 at 3:11 PM Frank Kloeker  > <mailto:eu...@arcor.de>> wrote:
> >
> > Am 2018-09-19 20:54, schrieb Andreas Jaeger:
> > > On 2018-09-19 20:50, Petr Kovar wrote:
> > >> Hi all,
> > >>
> > >> Based on our PTG discussion, I'd like to nominate Ian Y. Choi for
> > >> membership in the openstack-doc-core team. I think Ian doesn't
> > need an
> > >> introduction, he's been around for a while, recently being deeply
> > >> involved
> > >> in infra work to get us robust support for project team docs
> > >> translation and
> > >> PDF builds.
> > >>
> > >> Having Ian on the core team will also strengthen our
> > integration with
> > >> the i18n community.
> > >>
> > >> Please let the ML know should you have any objections.
> > >
> > > The opposite ;), heartly agree with adding him,
> > >
> > > Andreas
> >
> > ++
> >
> > Frank
> >
> >
> > 
> > __
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe:
> > openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> > <http://openstack-dev-requ...@lists.openstack.org?subject:unsubscribe>
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >
> >
> >
> > -- 
> > Kind regards,
> >
> > Melvin Hillsman
> > mrhills...@gmail.com <mailto:mrhills...@gmail.com>
> > mobile: (832) 264-2646
> >
> >
> > __
> > 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


-- 
Petr Kovar
Documentation Program Manager | Red Hat Virtualization
Customer Content Services | Red Hat Czech s.r.o.

__
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] [docs][i18n][ptg] Stein PTG Summary

[Petr Kovar]

Hi all,

Just wanted to share a summary of docs- and i18n-related meetings
and discussions we had in Denver last week during the Stein Project
Teams Gathering.

The overall schedule for all our sessions with additional comments and
meeting minutes can be found here:

https://etherpad.openstack.org/p/docs-i18n-ptg-stein

Our obligatory team picture (with quite a few members missing) can be
found here (courtesy of Foundation folks):

https://pmkovar.fedorapeople.org/DSC_4422.JPG

To summarize what I found most important:

OPS DOCS

We met with the Ops community to discuss the future of Ops docs. The plan
is for the Ops group to take ownership of the operations-guide (done),
ha-guide (in progress), and the arch-design guide (to do).

These three documents are being moved from openstack-manuals to their own
repos, owned by the newly formed Operations Documentation SIG.

See also
https://etherpad.openstack.org/p/ops-meetup-ptg-denver-2018-operations-guide
for more notes.

DOCS SITE & DESIGN

We discussed improving the site navigation, guide summaries (particularly
install-guide), adding a new index page for project team contrib guides, and
more. We met with the Foundation staff to discuss the possibility of getting
assistance with site design work.

We are also looking into accepting contributions from the Strategic Focus
Areas folks to make parts of the docs toolchain like openstackdocstheme more
easily reusable outside of the official OpenStack infrastructure.

We got feedback on front page template for project team docs, with Ironic
being the pilot for us.

We got input on restructuring and reworking specs site to make it easier
for users to understand that specs are not feature descriptions nor project
docs, and to make it more consistent in how the project teams publish their
specs. This will need to be further discussed with the folks owning the
specs site infra.

Support status badges showing at the top of docs.o.o pages may not work well
for projects following the cycle-with-intermediary release model, such as
Swift. We need to rethink how we configure and present the badges. 

There are also some UX bugs present for the badges
(https://bugs.launchpad.net/openstack-doc-tools/+bug/1788389).

TRANSLATIONS

We met with the infra team to discuss progress on translating project team
docs and, related to that, PDF builds.

With the Foundation staff, we discussed translating Edge and Container
whitepapers and related material.

REFERENCE, REST API DOCS AND RELEASE NOTES

With the QA team, we discussed the scope and purpose of the
/doc/source/reference documentation area in project docs. Because the
scope of /reference might be unclear and used inconsistently by project
teams, the suggestion is to continue with the original migration plan and
migrate REST API and possibly Release Notes under /doc/source, as described
in https://docs.openstack.org/doc-contrib-guide/project-guides.html. 

CONTRIBUTOR GUIDE

The OpenStack Contributor Guide was discussed in a separate session, see
https://etherpad.openstack.org/p/FC_SIG_ptg_stein for notes.

THAT'S IT?

Please add to the list if I missed anything important, particularly for
i18n.

Thank you to everybody who attended the sessions, and a special thanks goes
to all the PTG organizers!

Cheers,
pk

__
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] [docs] Nominating Ian Y. Choi for openstack-doc-core

[Petr Kovar]

Hi all,

Based on our PTG discussion, I'd like to nominate Ian Y. Choi for
membership in the openstack-doc-core team. I think Ian doesn't need an
introduction, he's been around for a while, recently being deeply involved
in infra work to get us robust support for project team docs translation and
PDF builds. 

Having Ian on the core team will also strengthen our integration with
the i18n community.

Please let the ML know should you have any objections.

Thanks,
pk

__
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] [docs][all] Testing installation guides for Rocky

[Petr Kovar]

Hi all,

With the Rocky release quickly approaching, I wanted to draw your attention
to installation guides testing. With each project team now maintaining
their own installation guide, and with the old coordinated effort to test
installation docs now retired, the Docs team recently updated guidelines
for IGs testing, you can find the instructions here:

https://docs.openstack.org/doc-contrib-guide/release/taskdetail.html#installation-guides-testing

As a reminder, all installation guides should be based on the common
installation guide found at https://docs.openstack.org/install-guide/ and
should be tested together with installation instructions from related
project teams docs:

https://docs.openstack.org/rocky/install/

We set up an Installation Guides Review Inbox that tracks all open patches
touching files under doc/source/install/ in project team repositories:

https://gerrit-dash-creator.readthedocs.io/en/latest/dashboards/dashboard_doc-install-guides.html

This will hopefully make it easier for project teams and individual docs
contributors to monitor and follow-up on changes happening across
OpenStack projects.

Thanks,
pk

__
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] [requirements][release][docs] FFE for openstackdocstheme 1.21.2

[Petr Kovar]

Hi all,

This is a request for an FFE to release openstackdocstheme 1.21.2.

This mostly fixes usability issues in rendering docs content, so we would
like to update the theme across all project team docs on docs.o.o. 

See also the update constraint request at
https://review.openstack.org/#/c/591020/.

Thanks,
pk

__
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] [docs][all] Front page template for project team documentation

[Petr Kovar]

Hi all,

A spin-off discussion in https://review.openstack.org/#/c/579177/ resulted
in an idea to update our RST conventions for headings level 2 and 3 so that
our guidelines follow recommendations from
http://docutils.sourceforge.net/docs/user/rst/quickstart.html#sections.

The updated conventions also better reflect what most projects have been
using already, regardless of what was previously in our conventions.

To sum up, for headings level 2, use dashes:

Heading 2
-

For headings level 3, use tildes:

Heading 3
~

For details on the change, see:

https://review.openstack.org/#/c/583239/1/doc/doc-contrib-guide/source/rst-conv/titles.rst

Thanks,
pk


On Fri, 29 Jun 2018 16:45:53 +0200
Petr Kovar  wrote:

> Hi all,
> 
> Feedback from the Queens PTG included requests for the Documentation
> Project to provide guidance and recommendations on how to structure common
> content typically found on the front page for project team docs, located at
> doc/source/index.rst in the project team repository.
> 
> I've created a new docs spec, proposing a template to be used by project
> teams, and would like to ask the OpenStack community and, specifically, the
> project teams, to take a look, submit feedback on the spec, share
> comments, ideas, or concerns:
> 
>   https://review.openstack.org/#/c/579177/
> 
> The main goal of providing and using this template is to make it easier for
> users to find, navigate, and consume project team documentation, and for
> contributors to set up and maintain the project team docs.
> 
> The template would also serve as the basis for one of the future governance
> docs tags, which is a long-term plan for the docs team.
> 
> Thank you,
> pk
> 
> __
> 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] [docs][all] Front page template for project team documentation

[Petr Kovar]

Hi all,

Feedback from the Queens PTG included requests for the Documentation
Project to provide guidance and recommendations on how to structure common
content typically found on the front page for project team docs, located at
doc/source/index.rst in the project team repository.

I've created a new docs spec, proposing a template to be used by project
teams, and would like to ask the OpenStack community and, specifically, the
project teams, to take a look, submit feedback on the spec, share
comments, ideas, or concerns:

  https://review.openstack.org/#/c/579177/

The main goal of providing and using this template is to make it easier for
users to find, navigate, and consume project team documentation, and for
contributors to set up and maintain the project team docs.

The template would also serve as the basis for one of the future governance
docs tags, which is a long-term plan for the docs team.

Thank you,
pk

__
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] [docs] Office hours instead of regular docs project meetings?

[Petr Kovar]

Hi again,

Haven't got much feedback so far on the meeting format change, so let's
proceed with turning formal docs meetings into office hours, keeping the
same time for now, until we decide to make further adjustments based on the
attendance.

The patch is here:

https://review.openstack.org/#/c/578398/

Thanks,
pk


On Wed, 20 Jun 2018 14:21:57 +0200
Petr Kovar  wrote:

> Hi all,
> 
> Due to low attendance in docs project meetings in recent months, I'd like
> to propose turning regular docs meetings into office hours, like many other
> OpenStack teams did.
> 
> My idea is to hold office hours every Wednesday, same time we held our
> docs meetings, at 16:00 UTC, in our team channel #openstack-doc where
> many community members already hang out and ask their questions about
> OpenStack docs.
> 
> Objections, comments, thoughts? 
> 
> Would there be interest to also hold office hours during a more
> APAC-friendly time slot? We'd need to volunteers to take care of it, please
> let me know!
> 
> Thanks,
> pk
> 
> __
> 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] [docs] Office hours instead of regular docs project meetings?

[Petr Kovar]

Hi all,

Due to low attendance in docs project meetings in recent months, I'd like
to propose turning regular docs meetings into office hours, like many other
OpenStack teams did.

My idea is to hold office hours every Wednesday, same time we held our
docs meetings, at 16:00 UTC, in our team channel #openstack-doc where
many community members already hang out and ask their questions about
OpenStack docs.

Objections, comments, thoughts? 

Would there be interest to also hold office hours during a more
APAC-friendly time slot? We'd need to volunteers to take care of it, please
let me know!

Thanks,
pk

__
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] [docs] Documentation meeting canceled

[Petr Kovar]

Hi all,

Apologies but have to cancel today's docs meeting due to a meeting
conflict. 

Have questions for the docs team? We hang out at #openstack-doc.

Thanks,
pk

__
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] [docs] Documentation meeting minutes for 2018-05-30

[Petr Kovar]

===
#openstack-doc: docteam
===


Meeting started by pkovar at 16:00:44 UTC.  The full logs are available
at
http://eavesdrop.openstack.org/meetings/docteam/2018/docteam.2018-05-30-16.00.log.html
.



Meeting summary
---

* Ops docs discussion  (pkovar, 16:05:40)
  * LINK:

http://lists.openstack.org/pipermail/openstack-operators/2018-May/015318.html
(pkovar, 16:05:45)
  * Ops community plans to take ownership of the ops, ha and
architecture guides  (pkovar, 16:05:49)
  * though the details and scope of content are to be agreed on yet
(pkovar, 16:06:38)
  * primarily, the community wants to work on ops guide  (pkovar,
16:07:02)

* Contributor Guide lead  (pkovar, 16:09:21)
  * After Mike P's departure, Kendall N is the new lead  (pkovar,
16:09:26)

* Default warning-is-error to True for non-legacy Sphinx projects
  (pkovar, 16:09:37)
  * LINK: https://review.openstack.org/#/c/559348/  (pkovar, 16:09:43)
  * Just merged today  (pkovar, 16:09:47)

* Vancouver Summit  (pkovar, 16:11:46)
  * Docs-i18N - Project Update recording available online, thanks to
everybody involved!  (pkovar, 16:11:51)
  * LINK: https://www.youtube.com/watch?v=FIGErKqXAy8  (pkovar,
16:11:55)

* Bug Triage Team  (pkovar, 16:12:36)
  * LINK: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams
(pkovar, 16:12:41)
  * Backlog stable, number of unresolved bugs started to decrease
recently  (pkovar, 16:12:45)

* Ops docs discussion  (pkovar, 16:22:56)
  * when migrating the ops guide, it might be easier for ops folks to
just copy the rst files from openstack-manuals  (pkovar, 16:22:58)
  * and save time on conversion from wiki  (pkovar, 16:23:35)



Meeting ended at 16:25:49 UTC.



People present (lines said)
---

* pkovar (39)
* dhellmann (15)
* openstack (3)
* stephenfin (3)



Generated by `MeetBot`_ 0.1.4


__
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] [docs] Documentation meeting today

[Petr Kovar]

Hi all,

The docs meeting will continue today at 16:00 UTC in
#openstack-doc, as scheduled. For more details, see the meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] [docs] Style guide for OpenStack documentation

[Petr Kovar]

On Thu, 17 May 2018 15:03:23 +
Jeremy Stanley <fu...@yuggoth.org> wrote:

> On 2018-05-17 16:35:36 +0200 (+0200), Petr Kovar wrote:
> > On Wed, 16 May 2018 17:05:15 +
> > Jeremy Stanley <fu...@yuggoth.org> wrote:
> > 
> > > On 2018-05-16 18:24:45 +0200 (+0200), Petr Kovar wrote:
> > > [...]
> > > > I'd like to propose replacing the reference to the IBM Style Guide
> > > > with a reference to the developerWorks editorial style guide
> > > > (https://www.ibm.com/developerworks/library/styleguidelines/).
> > > > This lightweight version comes from the same company and is based
> > > > on the same guidelines, but most importantly, it is available for
> > > > free.
> > > [...]
> > > 
> > > I suppose replacing a style guide nobody can access with one
> > > everyone can (modulo legal concerns) is a step up. Still, are there
> > > no style guides published under an actual free/open license? If
> > > https://www.ibm.com/developerworks/community/terms/use/ is correct
> > > then even accidental creation of a derivative work might be
> > > prosecuted as copyright infringement.
> > 
> > 
> > We don't really plan on reusing content from that site, just referring to
> > it, so is it a concern?
> [...]
> 
> A style guide is a tool. Free and open collaboration needs free
> (libre, not merely gratis) tools, and that doesn't just mean
> software. If, down the road, you want an OpenStack Documentation
> Style Guide which covers OpenStack-specific concerns to quote or
> transclude information from a more thorough guide, that becomes a
> derivative work and is subject to the licensing terms for the guide
> from which you're copying.

Okay, but that's not what we want to do here.
 
> There are a lot of other parallels between writing software and
> writing prose here beyond mere intellectual property concerns too.
> Saying that OpenStack Documentation is free and open, but then
> endorsing an effectively proprietary guide as something its authors
> should read and follow, sends a mixed message as to our position on
> open documentation (as a style guide is of course also documentation
> in its own right). On the other hand, recommending use of a style
> guide which is available under a free/libre open source license or
> within the public domain resonates with our ideals and principles as
> a community, serving only to strengthen our position on openness in
> all its endeavors (including documentation).

I'm all for openness but maintaining consistency is why style guides
matter. Switching to a different style guide would require the following:

1) agreeing on the right style guide,
2) reviewing our current style guidelines in doc-contrib-guide and updating
them as needed so that they comply with the new style guide, and,
3) ideally, begin reviewing all of OpenStack docs for style changes.

Do we have a volunteer who would be interested in taking on these tasks? If
not, we have to go for a quick fix. Either reference developerWorks, or, if
that's a concern, remove references to external style guides
altogether (and provide less information as a result). I prefer the former.

Cheers,
pk

__
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] [docs] Updates to openstack-doc-core

[Petr Kovar]

Hi all,

I'd like to thank Brian Moss and Maria Zlatkova who
recently stepped down from the docs core team, for all their
contributions to OpenStack documentation in the past years. 

Thank you for your community work, insight, and ideas you shared with
the community while in your core role. Hope to see you around OpenStack or
other open source project in the future!

Cheers,
pk

__
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] [docs] Style guide for OpenStack documentation

[Petr Kovar]

On Wed, 16 May 2018 17:05:15 +
Jeremy Stanley <fu...@yuggoth.org> wrote:

> On 2018-05-16 18:24:45 +0200 (+0200), Petr Kovar wrote:
> [...]
> > I'd like to propose replacing the reference to the IBM Style Guide
> > with a reference to the developerWorks editorial style guide
> > (https://www.ibm.com/developerworks/library/styleguidelines/).
> > This lightweight version comes from the same company and is based
> > on the same guidelines, but most importantly, it is available for
> > free.
> [...]
> 
> I suppose replacing a style guide nobody can access with one
> everyone can (modulo legal concerns) is a step up. Still, are there
> no style guides published under an actual free/open license? If
> https://www.ibm.com/developerworks/community/terms/use/ is correct
> then even accidental creation of a derivative work might be
> prosecuted as copyright infringement.


We don't really plan on reusing content from that site, just referring to
it, so is it a concern?

 
> http://www.writethedocs.org/guide/writing/style-guides/#selecting-a-good-style-guide-for-you
> mentions some more aligned with our community's open ideals, such as
> the 18F Content Guide (public domain), SUSE Documentation Style
> Guide (GFDL), GNOME Documentation Style Guide (GFDL), and the
> Writing Style Guide and Preferred Usage for DOD Issuances (public
> domain). Granted adopting one of those might lead to a need to
> overhaul some aspects of style in existing documents, so I can
> understand it's not a choice to be made lightly. Still, we should
> always consider embracing open process, and that includes using
> guidelines which we can freely derive and republish as needed.


I would be interested in hearing what other people think about that, but I
would strongly prefer to stick with the existing "publisher" as that creates
fewer issues than switching to a completely different style guide and
then having to adjust our guidelines based on the IBM guide, etc.

Thanks,
pk

__
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] [docs] Automating documentation the tripleo way?

[Petr Kovar]

On Wed, 16 May 2018 13:26:46 -0600
Wesley Hayutin  wrote:

> On Wed, May 16, 2018 at 3:05 PM Doug Hellmann  wrote:
> 
> > Excerpts from Wesley Hayutin's message of 2018-05-16 12:51:25 -0600:
> > > On Wed, May 16, 2018 at 2:41 PM Doug Hellmann 
> > wrote:
> > >
> > > > Excerpts from Petr Kovar's message of 2018-05-16 17:39:14 +0200:
> > > > > Hi all,
> > > > >
> > > > > In the past few years, we've seen several efforts aimed at automating
> > > > > procedural documentation, mostly centered around the OpenStack
> > > > > installation guide. This idea to automatically produce and verify
> > > > > installation steps or similar procedures was mentioned again at the
> > last
> > > > > Summit (https://etherpad.openstack.org/p/SYD-install-guide-testing).
> > > > >
> > > > > It was brought to my attention that the tripleo team has been
> > working on
> > > > > automating some of the tripleo deployment procedures, using a Bash
> > script
> > > > > with included comment lines to supply some RST-formatted narrative,
> > for
> > > > > example:
> > > > >
> > > > >
> > > >
> > https://github.com/openstack/tripleo-quickstart-extras/blob/master/roles/overcloud-prep-images/templates/overcloud-prep-images.sh.j2
> > > > >
> > > > > The Bash script can then be converted to RST, e.g.:
> > > > >
> > > > >
> > > >
> > https://thirdparty.logs.rdoproject.org/jenkins-tripleo-quickstart-queens-rdo_trunk-baremetal-dell_fc430_envB-single_nic_vlans-27/docs/build/
> > > > >
> > > > > Source Code:
> > > > >
> > > > >
> > > >
> > https://github.com/openstack/tripleo-quickstart-extras/tree/master/roles/collect-logs
> > > > >
> > > > > I really liked this approach and while I don't want to sound like
> > selling
> > > > > other people's work, I'm wondering if there is still an interest
> > among
> > > > the
> > > > > broader OpenStack community in automating documentation like this?
> > > > >
> > > > > Thanks,
> > > > > pk
> > > > >
> > > >
> > > > Weren't the folks doing the training-labs or training-guides taking a
> > > > similar approach? IIRC, they ended up implementing what amounted to
> > > > their own installer for OpenStack, and then ended up with all of the
> > > > associated upgrade and testing burden.
> > > >
> > > > I like the idea of trying to use some automation from this, but I
> > wonder
> > > > if we'd be better off extracting data from other tools, rather than
> > > > building a new one.
> > > >
> > > > Doug
> > > >
> > >
> > > So there really isn't anything new to create, the work is done and
> > executed
> > > on every tripleo change that runs in rdo-cloud.
> >
> > It wasn't clear what Petr was hoping to get. Deploying with TripleO is
> > only one way to deploy, so we wouldn't be able to replace the current
> > installation guides with the results of this work. It sounds like that's
> > not the goal, though.


Yes, I wasn't very clear on the goals as I didn't want to make too many
assumptions before learning about technical details from other people.
Ben's comments made me realize this approach would probably be best suited
for generating documents such as quick start guides or tutorials that are
procedural, yet they don't aim at describing multiple use cases.


> > >
> > > Instead of dismissing the idea upfront I'm more inclined to set an
> > > achievable small step to see how well it works.  My thought would be to
> > > focus on the upcoming all-in-one installer and the automated doc
> > generated
> > > with that workflow.  I'd like to target publishing the all-in-one tripleo
> > > installer doc to [1] for Stein and of course a section of tripleo.org.
> >
> > As an official project, why is TripleO still publishing docs to its own
> > site? That's not something we generally encourage.
> >
> > That said, publishing a new deployment guide based on this technique
> > makes sense in general. What about Ben's comments elsewhere in the
> > thread?
> >
> 
> I think Ben is referring to an older implementation and a slightly
> different design but still has some points that we would want to be mindful
> of.   I think this is a worthy effort to take another pass at this
> regarless to be honest as we've found a good combination of interested
> folks and sometimes the right people make all the difference.
> 
> My personal opinion is that I'm not expecting the automated doc generation
> to be upload ready to a doc server after each run.  I do expect it to do
> 95% of the work, and to help keep the doc up to date with what is executed
> in the latest releases of TripleO.


Would it make sense to consider a bot automatically creating patches
with content updates that would be then curated and reviewed by the docs
contributors?


>  Also noting the doc used is a mixture
> of static and generated documentation which I think worked out quite well
> in order to not soley rely on what is executed in ci.
> 
> So again, my thought is to create a small achievable goal and 

[openstack-dev] [docs] Style guide for OpenStack documentation

[Petr Kovar]

Hi all,

For OpenStack documentation contributors, we provide a basic style guide
that describes most important guidelines for writing, user interface
guidelines, and RST conventions:

https://docs.openstack.org/doc-contrib-guide/writing-style.html
https://docs.openstack.org/doc-contrib-guide/user-guidelines.html
https://docs.openstack.org/doc-contrib-guide/rst-conv.html

In these documents, we also refer to the printed IBM Style Guide for more
information. While this is a standard resource used by many technical
writers, we no longer have a group of dedicated writers working on our docs.
Also, the IBM Style Guide is not available online for free, making it
inaccessible to many in the community.

I'd like to propose replacing the reference to the IBM Style Guide with a
reference to the developerWorks editorial style guide
(https://www.ibm.com/developerworks/library/styleguidelines/). This
lightweight version comes from the same company and is based on the same
guidelines, but most importantly, it is available for free.

Any objections to this?

A related change:

https://review.openstack.org/#/c/562310/

I hope this change will make it much easier for our docs contributors to
consult style guidelines.

Thanks,
pk

__
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] [docs] Automating documentation the tripleo way?

[Petr Kovar]

Hi all,

In the past few years, we've seen several efforts aimed at automating
procedural documentation, mostly centered around the OpenStack
installation guide. This idea to automatically produce and verify
installation steps or similar procedures was mentioned again at the last
Summit (https://etherpad.openstack.org/p/SYD-install-guide-testing).

It was brought to my attention that the tripleo team has been working on
automating some of the tripleo deployment procedures, using a Bash script
with included comment lines to supply some RST-formatted narrative, for
example:

https://github.com/openstack/tripleo-quickstart-extras/blob/master/roles/overcloud-prep-images/templates/overcloud-prep-images.sh.j2

The Bash script can then be converted to RST, e.g.:

https://thirdparty.logs.rdoproject.org/jenkins-tripleo-quickstart-queens-rdo_trunk-baremetal-dell_fc430_envB-single_nic_vlans-27/docs/build/

Source Code:

https://github.com/openstack/tripleo-quickstart-extras/tree/master/roles/collect-logs

I really liked this approach and while I don't want to sound like selling
other people's work, I'm wondering if there is still an interest among the
broader OpenStack community in automating documentation like this?

Thanks,
pk

__
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] [docs] Documentation meeting today

[Petr Kovar]

Hi all,

The docs meeting will continue today at 16:00 UTC in
#openstack-doc, as scheduled. For more details, see the meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] FW: [docs][openstack-ansible] Stepping down from core

[Petr Kovar]

Alex,

Many thanks for your community leadership, your guidance and help that
was essential during the transition period, and really for all your efforts
that you have put into keeping the docs team up and running.

(Updated the perms accordingly.)

Thanks,
pk


On Wed, 9 May 2018 13:22:04 +
Alexandra Settle <a.set...@outlook.com> wrote:

> Man I’m so smart I sent a Dear John letter to the ML and forgot the subject 
> header.
> 
> SMOOTH MOVE.
> 
> From: Alexandra Settle <a.set...@outlook.com>
> Date: Wednesday, May 9, 2018 at 2:13 PM
> To: "OpenStack Development Mailing List (not for usage questions)" 
> <OpenStack-dev@lists.openstack.org>
> Cc: Petr Kovar <pko...@redhat.com>, Jean-Philippe Evrard 
> <jean-phili...@evrard.me>
> Subject: [openstack-dev][docs][openstack-ansible]
> 
> Hi all,
> 
> It is with a super heavy heart I have to say that I need to step down as core 
> from the OpenStack-Ansible and Documentation teams – and take a step back 
> from the community.
> 
> The last year has taken me in a completely different direction to what I 
> expected, and try as I might I just don’t have the time to be even a 
> part-time member of this great community :(
> 
> Although I’m moving on, and learning new things, nothing can beat the 
> memories of  SnowpenStack and Denver’s super awesome trains.
> 
> I know this isn’t some acceptance speech at the Oscars – but I just want to 
> thank the Foundation and everyone who donates to the travel program. Without 
> you guys, I wouldn’t have been a part of the community as much as I have been 
> and met all your lovely faces.
> 
> I have had such a great time being a part of something as exciting and new as 
> OpenStack, and I hope to continue to lurk in the background of IRC like a 
> total weirdo. I hope to perform some super shit karaoke with you all in 
> another part of the world :) (who knows, maybe I’ll just tag along to PTG’s 
> as a social outing… how cool am I?!)
> 
> I’d also like to thank Mugsie for this sweet shot which is the perfect 
> summary of my time with the OpenStack community. Read into this what you will:
> 
> [cid:image001.jpg@01D3E79F.EFDEF8E0]
> 
> Don’t be a stranger,
> 
> Alex
> 

> IRC: asettle
> Twitter: dewsday
> Email: a.set...@outlook.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

[openstack-dev] [docs] Documentation meeting canceled

[Petr Kovar]

Hi all,

Apologies but have to go offline now so canceling today's docs meeting. 

If you want to talk to the docs team, join #openstack-doc.

Thanks,
pk

__
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] [tc][docs] documenting openstack "constellations"

[Petr Kovar]

On Tue, 01 May 2018 10:08:23 -0400
Doug Hellmann  wrote:

> The TC has had an item on our backlog for a while (a year?) to
> document "constellations" of OpenStack components to make it easier
> for deployers and users to understand which parts they need to have
> the features they want [1].
> 
> John Garbutt has started writing the first such document [2], but
> as we talked about the content we agreed the TC governance repository
> is not the best home for it, so I have proposed creating a new
> repository [3].
> 
> In order to set up the publishing jobs for that repo so the content
> goes to docs.openstack.org, we need to settle the ownership of the
> repository.
> 
> I think it makes sense for the documentation team to "own" it, but
> I also think it makes sense for it to have its own review team
> because it's a bit different from the rest of the docs and we may
> be able to recruit folks to help who might not want to commit to
> being core reviewers for all of the documentation repositories. The
> TC members would also like to be reviewers, to get things going.
> 
> So, is the documentation team willing to add the new "constellations"
> repository under their umbrella?

Fine with me and thanks for bringing this up!

From the top of my head, this will also require updating the doc contrib
guide and the docs review dashboard.

https://docs.openstack.org/doc-contrib-guide/team-structure.html
https://is.gd/openstackdocsdashboard

Thanks,
pk

__
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] [docs] Documentation meeting minutes for 2018-04-18

[Petr Kovar]

===
#openstack-doc: docteam
===


Meeting started by pkovar at 16:02:48 UTC.  The full logs are available
at
http://eavesdrop.openstack.org/meetings/docteam/2018/docteam.2018-04-18-16.02.log.html
.



Meeting summary
---

* Open discussion  (pkovar, 16:04:23)

* docs PTL availability in April/May  (pkovar, 16:05:32)
  * pkovar to have limited online presence for the next 3 weeks
(pkovar, 16:06:10)
  * back in mid-May  (pkovar, 16:06:23)
  * will check email  (pkovar, 16:06:43)

* Vancouver Summit  (pkovar, 16:08:27)
  * Will have a shared 10+10 mins project update slot with i18n, see the
published schedule  (pkovar, 16:08:31)
  * LINK:

https://www.openstack.org/summit/vancouver-2018/summit-schedule/events/21627/docsi18n-project-onboarding
(pkovar, 16:09:09)
  * Frank (eumel8) started to fill out the content for project updates
on I18n part.  (ianychoi, 16:09:29)
  * stephenfin to talk about docs tooling updates  (pkovar, 16:10:16)

* Bug Triage Team  (pkovar, 16:19:01)
  * LINK: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams
(pkovar, 16:19:06)
  * if foks want to help, sign up  (pkovar, 16:19:55)
  * if folks want to help, sign up at
https://wiki.openstack.org/wiki/Documentation/SpecialityTeams for
the next slot  (pkovar, 16:20:36)
  * for the next cycle, we need to decide if we want to retire ha guide
which is pretty much unmaintained with more and more bugs being
filed  (pkovar, 16:25:39)

* Replacing pbr's autodoc feature with sphinxcontrib-apidoc  (pkovar,
  16:25:43)
  * LINK:
http://lists.openstack.org/pipermail/openstack-dev/2018-April/128986.html
(pkovar, 16:25:50)
  * kudos to stephenfin for spearheading this  (pkovar, 16:26:00)
  * LINK: https://review.openstack.org/#/c/509297/  (ianychoi, 16:31:09)



Meeting ended at 16:34:04 UTC.



People present (lines said)
---

* pkovar (61)
* ianychoi (22)
* stephenfin (5)
* openstack (4)
* openstackgerrit (1)



Generated by `MeetBot`_ 0.1.4


__
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] [docs] Documentation meeting today

[Petr Kovar]

Hi all,

The docs meeting will continue today at 16:00 UTC in
#openstack-doc, as scheduled. For more details, see the meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] Following the new PTI for document build, broken local builds

[Petr Kovar]

On Fri, 06 Apr 2018 15:52:46 +0100
Stephen Finucane  wrote:

> On Fri, 2018-04-06 at 08:02 -0500, Sean McGinnis wrote:
> > > > 
> > > > How can we enable warning_is_error in the gate with the new PTI? It's 
> > > > easy enough to add the -W flag in tox.ini for local builds, but as you 
> > > > say the tox job is never called in the gate. In the gate zuul checks 
> > > > for 
> > > > it in the [build_sphinx] section of setup.cfg:
> > > > 
> > > > https://git.openstack.org/cgit/openstack-infra/zuul-jobs/tree/roles/sphinx/library/sphinx_check_warning_is_error.pyLovel#n23
> > > > 
> > > > [...]
> > > 
> > > I'd be more in favour of changing the zuul job to build with the '-W'
> > > flag. To be honest, there is no good reason to not have this flag
> > > enabled. I'm not sure that will be a popular opinion though as it may
> > > break some projects' builds (correctly, but still).
> > > 
> > > I'll propose a patch against zuul-jobs and see what happens :)
> > > 
> > > Stephen
> > > 
> > 
> > I am in favor of this too. We will probably need to give some teams some 
> > time
> > to get warnings fixed though. I haven't done any kind of extensive audit of
> > projects, but from a few I looked through, there are definitely a few that 
> > are
> > not erroring on warnings and are likely to be blocked if we suddenly flipped
> > the switch and errored on those.
> >
> > This is a legitimate issue though. In Cinder we had -W in the tox docs job, 
> > but
> > since that is no longer being enforced in the gate, running "tox -e docs" 
> > from
> > a fresh clone of master was failing. We really do need some way to enforce 
> > this
> > so things like that do not happen.
> 
> This. While forcing work on teams to do busywork is undeniably A Very
> Bad Thing (TM), I do think the longer we leave this, the worse it'll
> get. The zuul-jobs [1] patch will probably introduce some pain for
> projects but it seems like inevitable pain and we're in the right part
> of the cycle in which to do something like this. I'd be willing to help
> projects fix issues they encounter, which I expect will be minimal for
> most projects.

I too think enforcing -W is the way to go, so count me in for the
broken docs build help.

Thanks for pushing this forward!

Cheers,
pk

__
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] [docs] Documentation meeting minutes for 2018-04-04

[Petr Kovar]

===
#openstack-doc: docteam
===


Meeting started by pkovar at 16:02:31 UTC.  The full logs are available
at
http://eavesdrop.openstack.org/meetings/docteam/2018/docteam.2018-04-04-16.02.log.html
.



Meeting summary
---

* dropdown menus on docs.o.o  (pkovar, 16:13:17)
  * design idea: re-implement dropdown menus as simple lists, as pointed
out by frank in https://review.openstack.org/#/c/556969/  (pkovar,
16:13:47)
  * to make the site more mobile friendly  (pkovar, 16:14:00)
  * LINK: https://ibb.co/coCMjx  (pkovar, 16:18:25)
  * ACTION: consider starting a thread / blueprint to discuss design
changes  (pkovar, 16:25:55)

* design ideas for docs.o.o  (pkovar, 16:30:22)
  * idea: make the landing pages with project lists more beautiful
(pkovar, 16:30:59)
  * like in https://www.openstack.org/software/project-navigator/ they
use all caps and bold for project names  (pkovar, 16:31:17)
  * idea: re-use mascot logos that would be stored in openstack-manuals
(pkovar, 16:34:10)

*   (pkovar, 16:38:37)

* vancouver summit  (pkovar, 16:38:46)
  * LINK:

https://www.openstack.org/summit/vancouver-2018/summit-schedule/global-search?t=docs
(pkovar, 16:39:38)
  * summit schedule is up with two  docs talks / sessions planned
(pkovar, 16:39:58)
  * co-located with i18n  (pkovar, 16:40:11)
  * thanks to our presenters  (pkovar, 16:40:29)

* documentation builds and PTI  (pkovar, 16:41:12)
  * updating PTI wrt  https://review.openstack.org/#/c/545377/ and
https://review.openstack.org/#/c/509297/ might be needed  (pkovar,
16:47:33)
  * seeking help from infra team, will probably need to create a spec
(pkovar, 16:47:56)
  * thanks ianychoi for driving project docs translations and pdf builds
(pkovar, 16:52:25)
  * thanks stephenfin for keeping projects updated wrt
sphinxcontrib-apidoc  (pkovar, 16:55:19)
  * LINK:
http://lists.openstack.org/pipermail/openstack-dev/2018-March/128817.html
(pkovar, 16:55:27)
  * LINK:
http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594.html
(pkovar, 16:55:34)



Meeting ended at 16:56:58 UTC.



People present (lines said)
---

* pkovar (75)
* ianychoi (30)
* openstack (3)
* openstackgerrit (2)
* mordred (2)



Generated by `MeetBot`_ 0.1.4


__
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] [docs] Documentation meeting today

[Petr Kovar]

Hi all,

The docs meeting will continue today at 16:00 UTC in
#openstack-doc, as scheduled. For more details, see the meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] [docs] Documentation meeting canceled

[Petr Kovar]

Hi all,

Apologies but have to cancel today's docs meeting due to a meeting
conflict. 

If you want to talk to the docs team, we're in #openstack-doc, as always!

Thanks,
pk

__
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] Adding "not docs" banner to specs website?

[Petr Kovar]

On Mon, 19 Mar 2018 14:57:58 +
Jim Rollenhagen  wrote:

> Ironic (and surely other projects) have had to point out many times that
> specs are a point in time design discussion, and not completed
> documentation. It's obviously too much work to go back and update specs
> constantly.
> 
> What do folks think about a banner at the top of the specs website (or each
> individual spec) that points this out? I'm happy to do the work if we agree
> it's a good thing to do. My suggested wording:
> 
> "NOTE: specifications are a point-in-time design reference, not up-to-date
> feature documentation."

Might be a good idea to also include a pointer to
https://docs.openstack.org/.

Thanks,
pk

__
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] [docs] Retiring openstack-doc-specs-core

[Petr Kovar]

Hi all,

For historical reasons, the docs team maintains a separate core group for
the docs-specs repo. With the new docs processes in place, we agreed at the
Rocky PTG to further simplify the docs group setup and retire
openstack-doc-specs-core by removing the existing members and adding
openstack-doc-core as a group member. 

That way, we will only have one core group, which better reflects the
current status of the team. Would there be any objections to this?

The current openstack-doc-specs-core membership can be found here:

https://review.openstack.org/#/admin/groups/384,members

Thanks,
pk

__
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] [First Contact][SIG] [PTG] Summary of Discussions

[Petr Kovar]

On Wed, 14 Mar 2018 10:38:37 -0500
Jay S Bryant <jungleb...@gmail.com> wrote:

> 
> 
> On 3/14/2018 10:04 AM, Petr Kovar wrote:
> > On Tue, 13 Mar 2018 18:57:24 -0500
> > Jay S Bryant <jungleb...@gmail.com> wrote:
> >
> >> Amy,
> >>
> >> The top level page for projects is referenced under documentation from
> >> here:  https://docs.openstack.org/queens/projects.html
> >>
> >> So, I think we have that one covered for people who are just looking for
> >> the top level documentation.
> > Yes, we have that covered. Just to clarify this a bit further, we also have
> > project lists like https://docs.openstack.org/queens/install/,
> > https://docs.openstack.org/queens/admin/ and
> > https://docs.openstack.org/queens/configuration/, what's missing is
> > https://docs.openstack.org/queens/contributor/.
> >
> > Cheers,
> > pk
> >
> Petr,
> 
> Do we need a contributor link per-release?  I thought in past 
> discussions that the contributor info should always go to latest and 
> that was why this is slightly different.

Right, that's a good point! I guess we should really just have
https://docs.openstack.org/latest/contributor/ then, perhaps
https://docs.openstack.org/contributor/ would be even better (with a
redirect). This means we need to treat templates for contributor project
docs as a special case and just point to /latest/contributor from all
release-specific docs.o.o landing pages.

Cheers,
pk


> >> On 3/13/2018 3:02 PM, Amy Marrich wrote:
> >>> I think if we're going to have that go to the development contributors
> >>> section (which makes sense) maybe we should also have ways of getting
> >>> to the deployment and admin docs as well?
> >>>
> >>> Amy (spotz)
> >>>
> >>> On Tue, Mar 13, 2018 at 2:55 PM, Jay S Bryant <jungleb...@gmail.com
> >>> <mailto:jungleb...@gmail.com>> wrote:
> >>>
> >>>
> >>>
> >>>  On 3/13/2018 1:38 PM, Petr Kovar wrote:
> >>>
> >>>  On Thu, 8 Mar 2018 12:54:06 -0600
> >>>  Jay S Bryant <jungleb...@gmail.com
> >>>  <mailto:jungleb...@gmail.com>> wrote:
> >>>
> >>>  Good overview.  Thank you!
> >>>
> >>>  One additional goal I want to mention on the list, for
> >>>  awareness, is the
> >>>  fact that we would like to eventually get some consistency
> >>>  to the pages
> >>>  that the 'Contributor Guide' lands on for each of the
> >>>  projects.  Needs
> >>>  to be a page that is friendly to new contributors, makes
> >>>  it easy to
> >>>  learn about the project and is not overwhelming.
> >>>
> >>>  What exactly that looks like isn't defined yet but I have
> >>>  talked to
> >>>  Manila about this.  They were interested in working
> >>>  together on this.
> >>>  Cinder and Manila will work together to get something
> >>>  consistent put
> >>>  together and then we can work on spreading that to other
> >>>  projects once
> >>>  we have agreement from the SIG that the approach is 
> >>> agreeable.
> >>>
> >>>  This is a good cross-project goal, I think. We discussed a
> >>>  similar approach
> >>>  in the docs room wrt providing templates to project teams that
> >>>  they can
> >>>  use to design their landing pages for admin, user,
> >>>  configuration docs; that
> >>>  would also include the main index page for project docs.
> >>>
> >>>  As for the project-specific contributor guides,
> >>>  https://docs.openstack.org/doc-contrib-guide/project-guides.html
> >>>  
> >>> <https://docs.openstack.org/doc-contrib-guide/project-guides.html>
> >>>  specifies
> >>>  that any contributor content should go to
> >>>  doc/source/contributor/. This will
> >>>  allow us to use templates to generate lists of links,
> >>>  similarly to what
> >>>  we do for other content areas.
> >>>
> >>>  Cheers,

Re: [openstack-dev] [First Contact][SIG] [PTG] Summary of Discussions

[Petr Kovar]

On Tue, 13 Mar 2018 18:57:24 -0500
Jay S Bryant <jungleb...@gmail.com> wrote:

> Amy,
> 
> The top level page for projects is referenced under documentation from 
> here:  https://docs.openstack.org/queens/projects.html
> 
> So, I think we have that one covered for people who are just looking for 
> the top level documentation.

Yes, we have that covered. Just to clarify this a bit further, we also have
project lists like https://docs.openstack.org/queens/install/,
https://docs.openstack.org/queens/admin/ and
https://docs.openstack.org/queens/configuration/, what's missing is
https://docs.openstack.org/queens/contributor/.

Cheers,
pk



> On 3/13/2018 3:02 PM, Amy Marrich wrote:
> > I think if we're going to have that go to the development contributors 
> > section (which makes sense) maybe we should also have ways of getting 
> > to the deployment and admin docs as well?
> >
> > Amy (spotz)
> >
> > On Tue, Mar 13, 2018 at 2:55 PM, Jay S Bryant <jungleb...@gmail.com 
> > <mailto:jungleb...@gmail.com>> wrote:
> >
> >
> >
> > On 3/13/2018 1:38 PM, Petr Kovar wrote:
> >
> > On Thu, 8 Mar 2018 12:54:06 -0600
> > Jay S Bryant <jungleb...@gmail.com
> > <mailto:jungleb...@gmail.com>> wrote:
> >
> > Good overview.  Thank you!
> >
> > One additional goal I want to mention on the list, for
> > awareness, is the
> > fact that we would like to eventually get some consistency
> > to the pages
> > that the 'Contributor Guide' lands on for each of the
> > projects.  Needs
> > to be a page that is friendly to new contributors, makes
> > it easy to
> > learn about the project and is not overwhelming.
> >
> > What exactly that looks like isn't defined yet but I have
> > talked to
> > Manila about this.  They were interested in working
> > together on this.
> > Cinder and Manila will work together to get something
> > consistent put
> > together and then we can work on spreading that to other
> > projects once
> > we have agreement from the SIG that the approach is agreeable.
> >
> > This is a good cross-project goal, I think. We discussed a
> > similar approach
> > in the docs room wrt providing templates to project teams that
> > they can
> > use to design their landing pages for admin, user,
> > configuration docs; that
> > would also include the main index page for project docs.
> >
> > As for the project-specific contributor guides,
> > https://docs.openstack.org/doc-contrib-guide/project-guides.html
> > <https://docs.openstack.org/doc-contrib-guide/project-guides.html>
> > specifies
> > that any contributor content should go to
> > doc/source/contributor/. This will
> > allow us to use templates to generate lists of links,
> > similarly to what
> > we do for other content areas.
> >
> > Cheers,
> > pk
> >
> >
> > 
> > __
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe:
> > openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> > 
> > <http://openstack-dev-requ...@lists.openstack.org?subject:unsubscribe>
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> > <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev>
> >
> > Petr,
> >
> > Good point.  I was trying to think of how to make a better landing
> > page for new contributors and you may have hit on the answer. 
> > RIght now when you click through from  here:
> > https://www.openstack.org/community
> > <https://www.openstack.org/community> You land at the top level
> > Cinder documentation page which is incredibly overwhelming for a
> > new person: https://docs.openstack.org/cinder/latest/
> > <https://docs.openstack.org/cinder/latest/>
> >
> > If the new contributor page instead lands here:
> > https://docs.openstack.org/cinder/latest/contributor/index.html
> > <https://docs.openstack.org/cinder/latest/contributor/index.html>
> >

Re: [openstack-dev] [First Contact][SIG] [PTG] Summary of Discussions

[Petr Kovar]

On Thu, 8 Mar 2018 12:54:06 -0600
Jay S Bryant  wrote:

> Good overview.  Thank you!
> 
> One additional goal I want to mention on the list, for awareness, is the 
> fact that we would like to eventually get some consistency to the pages 
> that the 'Contributor Guide' lands on for each of the projects.  Needs 
> to be a page that is friendly to new contributors, makes it easy to 
> learn about the project and is not overwhelming.
> 
> What exactly that looks like isn't defined yet but I have talked to 
> Manila about this.  They were interested in working together on this.  
> Cinder and Manila will work together to get something consistent put 
> together and then we can work on spreading that to other projects once 
> we have agreement from the SIG that the approach is agreeable.

This is a good cross-project goal, I think. We discussed a similar approach
in the docs room wrt providing templates to project teams that they can
use to design their landing pages for admin, user, configuration docs; that
would also include the main index page for project docs.

As for the project-specific contributor guides,
https://docs.openstack.org/doc-contrib-guide/project-guides.html specifies
that any contributor content should go to doc/source/contributor/. This will
allow us to use templates to generate lists of links, similarly to what
we do for other content areas.

Cheers,
pk


__
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] [docs] Documentation meeting canceled

[Petr Kovar]

Hi all,

Canceling today's docs meeting as there is not much to share beyond what
was in the PTG summary I sent. 

As always, we're in #openstack-doc if you want to talk to us!

Thanks,
pk

__
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] [docs][i18n][ptg] Rocky PTG Summary

[Petr Kovar]

Hi all,

Just wanted to share a summary of docs- and i18n-related meetings
and discussions we had in Dublin last week during the Rocky Project
Teams Gathering.

I think we can say both our teams, docs and i18n, are now pretty stable
member-wise, following new processes and goals set up earlier in the Pike
cycle. At the PTG, this was reflected in a rather fluctuating attendance of
3 to 12 ppl during the first two days. The meetings related to contributor
docs and community onboarding proved to be most popular and caught more
attention than others.

As with previous PTGs, it is important to note that many of our cores
couldn't attend, sadly. Traveling to OpenStack events remains a challenge
for many and this was again mentioned during the PTG feedback session.

The overall schedule for all our sessions with additional comments can be
found here:

https://etherpad.openstack.org/p/docs-i18n-ptg-rocky

Our team picture from the Croke Park stadium (with quite a few members
missing) can be found here (thanks Kendall!):

https://pmkovar.fedorapeople.org/ptg/docs-ptg-dublin-2018.jpg

To summarize what I found most important:

GOVERNANCE DOCS TAGS

We used to have the docs:follows-policy governance tag which in fact wasn't
implemented by the project teams and we eventually retired it in Pike.
Going forward, we want to propose several governance tags for projects to
use. Each tag would identify a conformance to a specific area of content
management and development, such following common glossary and terminology,
tested installation procedures, common content structure, etc. These would
serve as signs of maturity of each project.

CONTENT REUSE AND CROSS-REFERENCING

This is relevant to use cases such as sharing glossary term definitions
across project team docs and reusing common content for installation guides
across multiple releases. There are several alternatives we can look at
further, such as automatically submitting content changes between repos with
a bot, using Sphinx extensions (sphinx.ext.intersphinx), etc. More guidance
will need to be provided.

COMMON ORGANIZATION OF CONTENT

Some of the feedback we received from developers at the PTG was centered
around offering more guidance in the common organization of content in most
popular pages across project team docs. These certainly include
landing pages and front pages for each content category (installation,
usage, administration, reference, contribution, etc.).

SITE ANALYTICS

This is related to the previous point in that having access to some
of the site analytics data for docs.openstack.org would help the docs
project and project teams determine most popular content, content gaps, the
keywords users use when searching for content, etc. We discussed this with
a number of people from the Foundation.

INSTALLATION GUIDE TESTING

During the last cycles, there's been little interest from the community in
testing installation procedures in an organized high-level manner. For
Rocky, we will instead focus on providing more guidance on how to test
procedures on an individual level using Gerrit dashboards to track changes,
etc.

CONTRIBUTOR GUIDE

We met with some of the contributor-guide team members to discuss content
restructure and reuse, adding more content and cleaning up existing
contributor docs, such as the project-team-guide.

There's also a First Contact Special Interest Group etherpad that provides
more information on the subject of onboarding:

https://etherpad.openstack.org/p/FC_SIG_Rocky_PTG

TRANSLATIONS

Our i18n crew worked on enabling project team docs to be translatable,
starting with the openstack-ansible project as a pilot. 

THAT'S IT?

Please add to the list if I missed anything important, particularly for
i18n.

Thank you to everybody who attended the sessions, and a special thanks goes
to all the PTG organizers and the local staff who handled the Beast from the
East combined with storm Emma in Dublin in a truly professional manner!

Hope to see more of you at the next PTG in Secret Name of Next PTG Location!

Cheers,
pk

__
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] [docs][ptg][all] Documentation help for project teams

[Petr Kovar]

Hi all,

Similarly to the Queens PTG, we will have docs people around at the Rocky
PTG from Wednesday through Friday next week to help project teams with their
docs!

People from the docs team can meet with your project team to discuss your
documentation needs. Together, we can look into planning, structuring,
building and publishing of your project documentation.

The project team docs sessions are scheduled dynamically per the project and
docs teams' needs. 

Please use the docs-i18n-ptg-rocky etherpad to sign up for your team
(scroll down a bit):

https://etherpad.openstack.org/p/docs-i18n-ptg-rocky

See you at the PTG!

Cheers,
pk

__
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] [docs] About the convention to use '.' instead of 'source'.

[Petr Kovar]

On Sun, 18 Feb 2018 15:44:04 -0500
Doug Hellmann  wrote:

> Excerpts from Jeremy Stanley's message of 2018-02-18 16:01:52 +:
> > On 2018-02-18 03:55:51 -0600 (-0600), Monty Taylor wrote:
> > [...]
> > > I'd honestly argue in favor of assuming bash and using 'source'
> > > because it's more readable. We don't make allowances for alternate
> > > shells in our examples anyway.
> > > 
> > > I personally try to use 'source' vs . and $() vs. `` as
> > > aggressively as I can.
> > > 
> > > That said - I completely agree with fungi on the description of
> > > the tradeoffs of each direction, and I do think it's valuable to
> > > pick one for the docs.
> > 
> > Yes, it's not my call but I too would prefer more readable examples
> > over a strict adherence to POSIX. As long as we say somewhere that
> > our examples assume the user is in a GNU bash(1) environment and
> > that the examples may require minor adjustment for other shells, I
> > think that's a perfectly reasonable approach. If there's a
> > documentation style guide, that too would be a great place to
> > encourage examples following certain conventions such as source
> > instead of ., $() instead of ``, [] instead of test, an so on... and
> > provide a place to explain the rationale so that reviewers have a
> > convenient response they can link for bulk "improvements" which seem
> > to indicate ignorance of our reasons for these choices.
> 
> I've proposed reverting the style-guide change that seems to have led to
> this discussion in https://review.openstack.org/#/c/545718/2

FYI, we've just approved this.
 
Thanks,
pk

__
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] [docs] Documentation meeting minutes for 2018-02-21

[Petr Kovar]

===
#openstack-doc: docteam
===


Meeting started by pkovar at 16:01:11 UTC.  The full logs are available
at
http://eavesdrop.openstack.org/meetings/docteam/2018/docteam.2018-02-21-16.01.log.html
.



Meeting summary
---

* Rocky PTG  (pkovar, 16:05:12)
  * Planning etherpad for docs+i18n available  (pkovar, 16:05:17)
  * LINK: https://etherpad.openstack.org/p/docs-i18n-ptg-rocky  (pkovar,
16:05:23)
  * Sign up and tell us your ideas on what to discuss in the docs room
(pkovar, 16:05:28)
  * pkovar planning on organizing project docs helproom at the ptg, will
send a separate email about it  (pkovar, 16:06:23)
  * similarly to last year, the help room days to correlate with project
days to allow project teams to work with docs people  (pkovar,
16:07:08)

* Vancouver Summit  (pkovar, 16:09:04)
  * Looking to have a shared 10+10 mins project update slot with i18n
(pkovar, 16:09:09)
  * Looking for interested (co-)speakers  (pkovar, 16:09:15)

* Bug Triage Team  (pkovar, 16:11:28)
  * you can help the docs team with bug triaging by signing up  (pkovar,
16:12:30)
  * LINK: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams
(pkovar, 16:12:38)

* Open discussion  (pkovar, 16:13:18)
  * see you at the ptg next week!  (pkovar, 16:13:32)



Meeting ended at 16:20:26 UTC.



People present (lines said)
---

* pkovar (20)
* openstack (3)
* openstackgerrit (1)



Generated by `MeetBot`_ 0.1.4


__
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] [docs] Documentation meeting today

[Petr Kovar]

Hi all,

The docs meeting will continue today at 16:00 UTC in
#openstack-doc, as scheduled. For more details, see the meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] Debian OpenStack packages switching to Py3 for Queens

[Petr Kovar]

On Fri, 16 Feb 2018 17:49:37 +0100
Thomas Goirand <z...@debian.org> wrote:

> On 02/16/2018 03:42 PM, Petr Kovar wrote:
> > On Thu, 15 Feb 2018 09:31:19 +0100
> > Thomas Goirand <z...@debian.org> wrote:
> > 
> >> Hi,
> >>
> >> Since I'm getting some pressure from other DDs to actively remove Py2
> >> support from my packages, I'm very much considering switching all of the
> >> Debian packages for Queens to using exclusively Py3. I would have like
> >> to read some opinions about this. Is it a good time for such move? I
> >> hope it is, because I'd like to maintain as few Python package with Py2
> >> support at the time of Debian Buster freeze.
> >>
> >> Also, doing Queens, I've noticed that os-xenapi is still full of py2
> >> only stuff in os_xenapi/dom0. Can we get those fixes? Here's my patch:
> >>
> >> https://review.openstack.org/544809
> > 
> > Hey Thomas, slightly off-topic to this, but would it be a good idea to
> > resurrect OpenStack install guides for Debian if Debian packages are still
> > maintained?
> 
> Yes it would. I'm not sure where to start, since all the doc has moved
> to individual projects.

Right, I'd probably start with projects listed in minimal deployment:

https://docs.openstack.org/install-guide/openstack-services.html#minimal-deployment

Copying Ubuntu-specific pages might save some time. Old content is
still available from
https://github.com/openstack/openstack-manuals/tree/a1f1748478125ccd68d90a98ccc06c7ec359d3a0/doc/install-guide/source.

Best,
pk

__
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] Debian OpenStack packages switching to Py3 for Queens

[Petr Kovar]

On Thu, 15 Feb 2018 09:31:19 +0100
Thomas Goirand  wrote:

> Hi,
> 
> Since I'm getting some pressure from other DDs to actively remove Py2
> support from my packages, I'm very much considering switching all of the
> Debian packages for Queens to using exclusively Py3. I would have like
> to read some opinions about this. Is it a good time for such move? I
> hope it is, because I'd like to maintain as few Python package with Py2
> support at the time of Debian Buster freeze.
> 
> Also, doing Queens, I've noticed that os-xenapi is still full of py2
> only stuff in os_xenapi/dom0. Can we get those fixes? Here's my patch:
> 
> https://review.openstack.org/544809

Hey Thomas, slightly off-topic to this, but would it be a good idea to
resurrect OpenStack install guides for Debian if Debian packages are still
maintained?

Thanks for working on Debian packages.

Cheers,
pk

__
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] [docs] Documentation meeting minutes for 2018-02-07

[Petr Kovar]

===
#openstack-doc: docteam
===


Meeting started by pkovar at 16:00:38 UTC.  The full logs are available
at
http://eavesdrop.openstack.org/meetings/docteam/2018/docteam.2018-02-07-16.00.log.html
.



Meeting summary
---

* retired internal -core mailing list discussions on new core
  nominations and started discussing core team changes on -dev  (pkovar,
  16:07:28)

* Add deprecation badges to docs.o.o  (pkovar, 16:08:36)
  * LINK: https://review.openstack.org/#/c/530142/  (pkovar, 16:08:41)
  * Under review, further changes required in openstackdocstheme
(pkovar, 16:08:45)

* Rocky PTG  (pkovar, 16:12:12)
  * Planning etherpad for docs+i18n available  (pkovar, 16:12:17)
  * LINK: https://etherpad.openstack.org/p/docs-i18n-ptg-rocky  (pkovar,
16:12:22)
  * Sign up and tell us your ideas on what to discuss in the docs room
(pkovar, 16:12:26)

* Vancouver Summit  (pkovar, 16:13:45)
  * Planning to have a shared 10+10 mins project update slot with i18n
(pkovar, 16:14:00)
  * Looking for interested (co-)speakers  (pkovar, 16:14:34)

* Bug Triage Team  (pkovar, 16:17:17)
  * LINK: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams
(pkovar, 16:17:23)

* Open discussion  (pkovar, 16:18:33)



Meeting ended at 16:22:51 UTC.



People present (lines said)
---

* pkovar (33)
* openstack (3)
* jamesmcarthur (1)



Generated by `MeetBot`_ 0.1.4


__
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] [docs] Documentation meeting today

[Petr Kovar]

Hi all,

The docs meeting will continue today at 16:00 UTC in
#openstack-doc, as scheduled. For more details, see the meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] [docs][ptl] PTL candidacy for Docs

[Petr Kovar]

Hi all,

I'd like to announce my candidacy for PTL of the Docs project for Rocky.

I've been the Docs PTL since Queens and besides my work on OpenStack docs, I
also contribute to the RDO Project.

During the Queens cycle, we mostly finalized our work on project docs
migration, we also continued assisting project teams with their setup for
project-specific content, we improved our template system for
docs.openstack.org, stopped unpublishing EOL content, and more.

We now also have a docs mission statement to help us identify project goals
within a broader OpenStack context. For Rocky, we need to review and
revisit the team goals and continue working on areas like docs theme and
build automation, alongside the content restructure and rework of what is
left in openstack-manuals.

Our Rocky PTG planning is well underway but I think it is now more important
than ever that we keep the project as open as possible to all potential
documentation contributors, regardless of whether they attend in-person
events or not, this also includes drive-by contributions.

Thank you,
pk

__
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] [docs] Core review stats for February

[Petr Kovar]

Hi all,

This is more of an FYI for people interested in all things docs that the
docs core team agreed on opening up the process for new docs core
nominations or removals. Instead of using a private list, this will now be
discussed in public, using the openstack-dev list, as documented here:

https://docs.openstack.org/doc-contrib-guide/docs-review.html#achieving-core-reviewer-status

The docs core team is the core for openstack-manuals, openstackdocstheme,
and openstack-doc-tools, and, as a group member, also for subteam repos
organized under the Docs project, such as contributor-guide or security-doc.

For February, I don't recommend any changes to the core team, which is now
pretty stable. If you have any suggestions, please let us know, preferably,
in this thread.

Thanks,
pk

__
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] [docs] Documentation meeting minutes for 2018-01-24

[Petr Kovar]

===
#openstack-doc: docteam
===


Meeting started by pkovar at 16:00:51 UTC.  The full logs are available
at
http://eavesdrop.openstack.org/meetings/docteam/2018/docteam.2018-01-24-16.00.log.html
.



Meeting summary
---

* roll call  (pkovar, 16:01:02)

* Rocky PTG  (pkovar, 16:05:52)
  * LINK: https://www.openstack.org/ptg/  (pkovar, 16:05:57)
  * Planning etherpad for docs+i18n created  (pkovar, 16:06:02)
  * LINK: https://etherpad.openstack.org/p/docs-i18n-ptg-rocky  (pkovar,
16:06:09)
  * Sign up and tell us your preference wrt parcel time into small
chunks or have full-day focus on one team agenda?  (pkovar,
16:06:13)
  * as dhellmann pointed out adding badges will require further work in
openstackdocstheme  (pkovar, 16:21:48)
  * ACTION: ensure https://review.openstack.org/#/c/530142/ is on the
ptg agenda  (pkovar, 16:22:50)
  * action taken, resolved  (pkovar, 16:25:43)

* Bug Triage Team  (pkovar, 16:35:06)
  * LINK: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams
(pkovar, 16:35:12)
  * Updated docs for documentation bug triaging  (pkovar, 16:35:24)
  * LINK: https://docs.openstack.org/doc-contrib-guide/doc-bugs.html
(pkovar, 16:35:28)

* Open discussion  (pkovar, 16:41:43)
  * chason added a topic idea for ptg: Project bugs with a "doc" tag
will notify openstack-manuals  (pkovar, 16:57:22)



Meeting ended at 16:58:01 UTC.



Action items, by person
---

* openstack
  * ensure https://review.openstack.org/#/c/530142/ is on the ptg agenda



People present (lines said)
---

* pkovar (88)
* asettle (20)
* chason (16)
* dhellmann (9)
* openstack (3)
* stephenfin (1)



Generated by `MeetBot`_ 0.1.4


__
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] [docs] Documentation meeting today

[Petr Kovar]

Hi all,

The docs meeting will continue today at 16:00 UTC in
#openstack-doc, as scheduled. For more details, see the meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] [docs] Documentation meeting minutes for 2018-01-10

[Petr Kovar]

===
#openstack-doc: docteam
===


Meeting started by pkovar at 16:00:32 UTC.  The full logs are available
at
http://eavesdrop.openstack.org/meetings/docteam/2018/docteam.2018-01-10-16.00.log.html
.



Meeting summary
---

* roll call  (pkovar, 16:00:49)

* PDF builds  (pkovar, 16:04:06)
  * LINK: https://review.openstack.org/#/c/509297/  (pkovar, 16:04:15)

* Docs retention policy changes  (pkovar, 16:08:59)
  * LINK:

http://specs.openstack.org/openstack/docs-specs/specs/queens/retention-policy.html
(pkovar, 16:09:07)
  * we have a pending review for adding deprecation badges  (pkovar,
16:10:11)
  * LINK: https://review.openstack.org/#/c/530142/  (pkovar, 16:10:23)

* Rocky PTG  (pkovar, 16:12:12)
  * LINK: https://www.openstack.org/ptg/  (pkovar, 16:12:29)
  * Planning etherpad for docs+i18n created  (pkovar, 16:12:38)
  * LINK: https://etherpad.openstack.org/p/docs-i18n-ptg-rocky  (pkovar,
16:12:53)
  * Sign up and tell us your preference wrt parcel time into small
chunks or have full-day focus on one team agenda?  (pkovar,
16:13:02)

* Bug Triage Team  (pkovar, 16:14:50)
  * you can still sign up  (pkovar, 16:15:09)
  * LINK: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams
(pkovar, 16:15:11)

* PDF builds  (pkovar, 16:16:26)
  * LINK:
http://lists.openstack.org/pipermail/openstack-dev/2017-November/124863.html
(ianychoi, 16:17:14)
  * updating PTI will be needed in order to unblock the pdf spec
(pkovar, 16:42:32)
  * let's discuss again before the rocky ptg and then try to work
together on the update at the ptg  (pkovar, 16:43:08)
  * LINK:

https://github.com/openstack/openstackdocstheme/commit/9219e0b38838bb8c788849b792180e4502e2b3a6
(pkovar, 16:44:55)
  * LINK: https://review.openstack.org/#/c/532163/  (stephenfin,
16:48:49)
  * openstackdocstheme  1.18.0  on the way but blocked by
https://review.openstack.org/#/c/532163/  (pkovar, 16:49:06)

* Open discussion  (pkovar, 16:53:38)



Meeting ended at 16:58:55 UTC.



People present (lines said)
---

* pkovar (73)
* ianychoi (33)
* stephenfin (14)
* tosky (3)
* openstack (3)
* d0ugal (1)



Generated by `MeetBot`_ 0.1.4


__
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] [docs] Documentation meeting today

[Petr Kovar]

Hi all,

The docs meeting will continue today at 16:00 UTC in
#openstack-doc, as scheduled. For more details, see the meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] [os-api-ref][doc] Adding openstack-doc-core to os-api-ref

[Petr Kovar]

On Thu, 4 Jan 2018 16:06:53 +
Graham Hayes  wrote:

> On 04/01/18 15:39, Stephen Finucane wrote:
> > I'm not sure what the procedure for this is but here goes.
> > 
> > I've noticed that the 'os-api-ref' project seems to have its own group
> > of cores [1], many of whom are no longer working on OpenStack (at
> > least, not full-time), and has a handful of open patches against it
> > [2]. Since the doc team has recently changed its scope from writing
> > documentation to enabling individual projects to maintain their own
> > docs, we've become mainly responsible for projects like 'openstack-doc-
> > theme'. Given that the 'os-api-ref' project is a Sphinx thing required
> > for multiple OpenStack projects, it seems like something that
> > could/should fall into the doc team's remit.
> > 
> > I'd like to move this project into the remit of the 'openstack-doc-
> > core' team, by way of removing the 'os-api-ref-core' group or adding
> > 'openstack-doc-core' to the list of included groups. In both cases,
> > existing active cores will be retained. Do any of the existing 'os-api-
> > ref' cores have any objections to this?
> 
> No objection from me
> 
> > Stephen
> > 
> > PS: I'm not sure how this affects things from a release management
> > perspective. Are there PTLs for these sorts of projects?
> 
> It does seem like a docs tooling thing, so maybe moving it to the docs
> project umbrella might be an idea?

What we do for other projects under that umbrella (such as
contributor-guide) is that we add openstack-doc-core as a group
member, as Stephen mentioned. This allows for other contributors to become
cores even if they are not interested in other aspects of the docs team's
work.

But I'm fine with whatever works for the current cores.

Thanks,
pk

__
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] [docs][ptls][all] documentation retention policy changes

[Petr Kovar]

On Tue, 17 Oct 2017 19:15:32 +0200
Petr Kovar <pko...@redhat.com> wrote:

> On Thu, 28 Sep 2017 12:51:18 -0400
> Doug Hellmann <d...@doughellmann.com> wrote:
> 
> > At the Queens PTG in Denver the documentation team members present
> > discussed a new retention policy for content published to
> > docs.openstack.org. I have a spec up for review to document that
> > policy and the steps needed to implement it. This policy will affect
> > all projects, now that most of the documentation is managed by
> > project teams. Please take a few minutes to review it, or at the
> > very least have your documentation team liaison do so.
> > 
> > https://review.openstack.org/#/c/507629
> 
> We've just approved this spec. Thanks Doug for putting this together!
> 
> With this spec approved, we'll no longer delete EOL docs and will also
> restore (some of the) Mitaka content back to docs.openstack.org/mitaka.
> 
> We still need help with updating the Ocata branch and (writing
> a spec) and implementing badges to warn users about unsupported content. If
> you can help with these, please let us know (and see the thread Flagging
> deprecated releases started by Jimmy).

Just a FYI, we have now restored old guide content for Mitaka, Newton and
Ocata, available from here:

https://docs.openstack.org/mitaka/
https://docs.openstack.org/newton/
https://docs.openstack.org/ocata/

Badges are a WIP.

Thanks to everybody who helped with this initiative.

Cheers,
pk

__
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] [docs] Documentation meeting minutes for 2017-12-13

[Petr Kovar]

===
#openstack-doc: docteam
===


Meeting started by pkovar at 16:01:40 UTC.  The full logs are available
at
http://eavesdrop.openstack.org/meetings/docteam/2017/docteam.2017-12-13-16.01.log.html
.



Meeting summary
---

* roll call  (pkovar, 16:02:04)

* Docs retention policy changes  (pkovar, 16:06:21)
  * LINK:

http://specs.openstack.org/openstack/docs-specs/specs/queens/retention-policy.html
(pkovar, 16:06:27)
  * LINK:
https://blueprints.launchpad.net/openstack-manuals/+spec/retention-policy
(pkovar, 16:06:49)
  * Good progress, waiting on changes to be merged  (pkovar, 16:06:56)
  * Flagging deprecated releases  (pkovar, 16:11:15)
  * LINK:
http://lists.openstack.org/pipermail/openstack-dev/2017-October/123381.html
(pkovar, 16:11:21)

* Rocky PTG  (pkovar, 16:17:59)
  * LINK: https://www.openstack.org/ptg/  (pkovar, 16:18:06)
  * Planning etherpad for docs+i18n created  (pkovar, 16:18:13)
  * LINK: https://etherpad.openstack.org/p/docs-i18n-ptg-rocky  (pkovar,
16:18:19)
  * Sign up and tell us your preference wrt parcel time into small
chunks or have full-day focus on one team agenda?  (pkovar,
16:18:26)
  * ... on the eherpad  (pkovar, 16:18:51)
  * we will be joined by people involved in the contrib guide effort
(pkovar, 16:19:36)
  * ... and upstream institute  (pkovar, 16:20:07)
  * LINK: Contributor Guide https://docs.openstack.org/contributors/
(pkovar, 16:20:30)
  * ACTION: add your own topics to the planning etherpad  (pkovar,
16:21:05)

* removed unused docs:follows-policy tag  (pkovar, 16:23:11)
  * LINK: https://review.openstack.org/#/c/524217/  (pkovar, 16:23:18)
  * new docs tags to be discussed at PTG  (pkovar, 16:23:24)

* changes to the docs core team  (pkovar, 16:24:14)
  * Anne Gentle stepped down from the core team  (pkovar, 16:24:31)
  * thanks Anne for your leadership and involvement in the docs project
since the very beginning!  (pkovar, 16:24:37)

* Project Liaisons for  First Contact SIG  (pkovar, 16:25:58)
  * LINK: https://wiki.openstack.org/wiki/First_Contact_SIG  (pkovar,
16:26:06)
  * Anyone interested in being the docs project liaison?  (pkovar,
16:26:12)

* PDF builds  (pkovar, 16:29:22)
  * LINK: https://review.openstack.org/#/c/509297/  (pkovar, 16:29:30)
  * LINK:
http://lists.openstack.org/pipermail/openstack-dev/2017-November/124863.html
(pkovar, 16:32:43)
  * ACTION: follow up on the pdf build thread  (pkovar, 16:33:07)

* Bug Triage Team  (pkovar, 16:44:08)
  * LINK: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams
(pkovar, 16:44:21)
  * chason signed up for
https://wiki.openstack.org/wiki/First_Contact_SIG#Project_Liaisons
(pkovar, 16:47:33)
  * ACTION: file bugs, triage bugs, repeat  (pkovar, 16:48:10)

* Open discussion  (pkovar, 16:50:14)
  * next meeting scheduled for Jan 10 2018  (pkovar, 16:52:46)



Meeting ended at 16:55:37 UTC.



People present (lines said)
---

* pkovar (93)
* ianychoi (11)
* jamesmcarthur (10)
* AJaeger (6)
* chason (6)
* openstack (3)



Generated by `MeetBot`_ 0.1.4


__
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] [docs] Documentation meeting today

[Petr Kovar]

Hi all,

The docs meeting will continue today at 16:00 UTC in
#openstack-doc, as scheduled. For more details, and the agenda, see the meeting 
page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] [docs][i18n] Planning for Rocky PTG

[Petr Kovar]

Hi all,

At the last docs meeting, we agreed to start planning on what
docs and i18n topics to focus on during the docs meetup at the upcoming
Dublin PTG. Apart from reviewing our progress on action items defined at
the previous PTG, we also want to cover other high-priority areas,
infrastructure or content-related.

We have a shared docs+i18n planning etherpad, but for now, keep the
topics for docs and i18n separate. 

If you plan to take part in the docs+i18n sessions, please sign up, state
your preference as to whether you want to meet on the theme days or during
the team days of the PTG week, and finally add your own ideas for
discussion:

https://etherpad.openstack.org/p/docs-i18n-ptg-rocky

Thanks,
pk

__
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] [docs] Closing down openstack-d...@lists.openstack.org

[Petr Kovar]

Hi all,

As previously announced, I'm sending a final notice that we are closing
down openstack-d...@lists.openstack.org.

Please use openstack-dev@lists.openstack.org with the [docs] tag in
subject for documentation-related discussions.

No new subscriptions or postings will be allowed for
openstack-d...@lists.openstack.org but we plan to retain the list archives
for historical reference.

Thanks,
pk

__
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] [docs] Documentation meeting minutes for 2017-11-29

[Petr Kovar]

===
#openstack-doc: docteam
===


Meeting started by pkovar at 16:00:16 UTC.  The full logs are available
at
http://eavesdrop.openstack.org/meetings/docteam/2017/docteam.2017-11-29-16.00.log.html
.



Meeting summary
---

* roll call  (pkovar, 16:00:42)

* Docs team vision document  (pkovar, 16:05:20)
  * Merged  (pkovar, 16:05:28)
  * LINK: https://docs.openstack.org/doc-contrib-guide/team-vision.html
(pkovar, 16:05:33)

* Docs retention policy changes  (pkovar, 16:07:32)
  * WIP  (pkovar, 16:07:40)
  * LINK: https://review.openstack.org/#/c/521961/  (pkovar, 16:07:47)
  * ACTION: eumel8 to ask the language teams about restoring language
landing pages  (pkovar, 16:13:26)
  * Flagging deprecated releases  (pkovar, 16:15:21)
  * LINK:
http://lists.openstack.org/pipermail/openstack-dev/2017-October/123381.html
(pkovar, 16:15:22)
  * jamesmcarthur to work on patch, dhellmann to help with Q's.
(pkovar, 16:17:58)
  * LINK: https://review.openstack.org/#/c/509297/  (pkovar, 16:24:17)
  * pdf spec ^  (pkovar, 16:24:32)
  * think about providing a watermark too, possibly as a separate patch.
good for pdfs  (pkovar, 16:25:07)

* OpenStack Summit Sydney  (pkovar, 16:26:13)
  * Summary of docs sessions posted  (pkovar, 16:26:18)
  * LINK:

https://www.rdoproject.org/blog/2017/11/summary-openstack-summit-docs-sessions/
(pkovar, 16:26:23)

* Rocky PTG  (pkovar, 16:27:40)
  * Planning etherpad for docs+i18n created  (pkovar, 16:27:48)
  * LINK: https://etherpad.openstack.org/p/docs-i18n-ptg-rocky  (pkovar,
16:27:54)
  * Parcel time into small chunks or have full-day focus on one team
agenda?  (pkovar, 16:28:43)
  * for PTG, two days planned, ca.  8-12 people  (pkovar, 16:35:19)
  * ACTION: send an email to start gathering input wrt ptg agenda
(pkovar, 16:36:59)
  * ACTION: pkovar to send an email for both teams to openstack-dev
(pkovar, 16:39:14)
  * ACTION: when getting input, let's also ask people to sign up and
share their day and time preferences  (pkovar, 16:42:54)

* closing openstack-docs mailing list  (pkovar, 16:45:55)
  * ACTION: close the list for new mail and subscribers tomorrow
(pkovar, 16:49:29)

* Branches vs everything in master  (pkovar, 16:51:11)

* sitemap automation suggestions  (pkovar, 16:52:49)
  * LINK:
http://lists.openstack.org/pipermail/openstack-dev/2017-October/123228.html
(pkovar, 16:52:56)
  * ACTION: mguiney working on this  (pkovar, 16:55:37)

* Bug Triage Team  (pkovar, 16:57:48)
  * LINK: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams
(pkovar, 16:57:52)

* Open discussion  (pkovar, 16:59:44)

* PDF builds  (pkovar, 17:00:56)
  * LINK: https://review.openstack.org/#/c/509297/  (pkovar, 17:01:02)
  * the proposal needs more review from other people  (pkovar, 17:01:11)



Meeting ended at 17:01:57 UTC.



Action items, by person
---

* eumel8
  * eumel8 to ask the language teams about restoring language landing
pages
* mguiney
  * mguiney working on this
* openstack
  * pkovar to send an email for both teams to openstack-dev
* pkovar
  * pkovar to send an email for both teams to openstack-dev
* **UNASSIGNED**
  * send an email to start gathering input wrt ptg agenda
  * when getting input, let's also ask people to sign up and share their
day and time preferences
  * close the list for new mail and subscribers tomorrow



People present (lines said)
---

* pkovar (151)
* eumel8 (31)
* jamesmcarthur (17)
* dhellmann (11)
* jungleboyj (7)
* openstack (4)
* chason (3)
* mguiney (1)



Generated by `MeetBot`_ 0.1.4


__
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] [docs] Documentation meeting Wednesday

[Petr Kovar]

Hi all,

The docs meeting will continue tomorrow, Wednesday at 16:00 UTC in
#openstack-doc, as scheduled. For more details, and the agenda, see the meeting 
page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] [docs] Summary of Summit docs sessions

[Petr Kovar]

Hi all,

To keep everybody updated on the recent docs meetups and IRL conversations,
I wanted to share a summary of the Sydney Summit docs sessions that I
took part in. Though a bit belated, posting it just in time before the next
docs meeting this Wednesday.

https://www.rdoproject.org/blog/2017/11/summary-openstack-summit-docs-sessions/

If I missed any docs-related discussions at the Summit, please let the
community know in this thread.

Cheers,
pk

__
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] [OpenStack-docs] [all] Changes to releasenotes and docs build jobs

[Petr Kovar]

On Thu, 23 Nov 2017 09:38:34 +0100
Thierry Carrez  wrote:

> Doug Hellmann wrote:
> > 
> >> On Nov 22, 2017, at 11:22 AM, Ian Y. Choi  wrote:
> >>
> >> Hello,
> >>
> >> Maybe there would be some chance to be also considered with PDF builds?
> >>
> >> I created an WIP patch on openstack/horizon repository [1] to highlight
> >> which changes to be needed for PDF build support on docs and releasenotes.
> >>
> >> Although there is currently one warning using "python setup.py 
> >> build_sphinx" [2],
> >> I think the warning would be quite fine now since using sphinx-build 
> >> command with
> >> "-b latex" option works well and such command execution is how PTI is 
> >> going from my understanding [3].
> > 
> > It does make sense to build PDFs. Do you think we want to always build them?
> > 
> >>
> >> (I am also copying this to openstack-docs mailing list for [4].)
> > 
> > We really really need to stop using that separate mailing list. Now that 
> > the project teams are managing their own documentation, we should just have 
> > the docs discussions on the -dev list so everyone can participate.
> 
> +1
> How about closing that list?

Let me send a final reminder and then we can set the list to read-only in
mailman admin, hopefully. 

Cheers,
pk

__
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] [OpenStack-docs] [docs] Next documentation meeting

[Petr Kovar]

All,

Please consider today's meeting canceled. 

Thanks,
pk


> From: "Petr Kovar" <pko...@redhat.com>
> To: openstack-dev@lists.openstack.org
> Cc: "enstack.org" <openstack-d...@lists.openstack.org>
> Sent: Tuesday, November 14, 2017 11:37:39 AM
> Subject: [OpenStack-docs] [docs] Next documentation meeting
> 
> Hi docs people,
> 
> Our next documentation meeting is scheduled for Wednesday, 15th November.
> As I'm traveling this week, I'll be unable to host the meeting. Is
> anybody available to run the meeting in my stead?
> 
> If not, let's cancel it and meet in two weeks.
> 
> Thank you,
> pk
> 
> ___
> OpenStack-docs mailing list
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 

__
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] [docs] Next documentation meeting

[Petr Kovar]

Hi docs people,

Our next documentation meeting is scheduled for Wednesday, 15th November.
As I'm traveling this week, I'll be unable to host the meeting. Is
anybody available to run the meeting in my stead? 

If not, let's cancel it and meet in two weeks.

Thank you,
pk

__
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] [docs] Documentation new meeting time - Wednesday at 16:00 UTC

[Petr Kovar]

Below are the meeting minutes from today's docs team meeting.

===
#openstack-doc: docteam
===


Meeting started by pkovar at 16:00:43 UTC.  The full logs are available
at
http://eavesdrop.openstack.org/meetings/docteam/2017/docteam.2017-11-01-16.00.log.html
.



Meeting summary
---

* Docs team vision document  (pkovar, 16:06:19)
  * At final review  (pkovar, 16:06:26)
  * LINK: https://review.openstack.org/#/c/514779/  (pkovar, 16:06:31)
  * Sent a reminder asking for more input  (pkovar, 16:06:37)
  * Let's close by Thu, before the Summit  (pkovar, 16:06:47)

* Docs retention policy changes  (pkovar, 16:10:16)
  * We've just approved this spec. Thanks Doug for putting this
together!  (pkovar, 16:10:27)
  * LINK: https://review.openstack.org/#/c/507629  (pkovar, 16:10:33)
  * Flagging deprecated releases  (pkovar, 16:10:52)
  * LINK:
http://lists.openstack.org/pipermail/openstack-dev/2017-October/123381.html
(pkovar, 16:10:57)

* Branches vs "everything in master"  (pkovar, 16:13:28)
  * Common Install Guide content should be branched/split up
per-release?  (pkovar, 16:13:50)
  * LINK: https://review.openstack.org/#/c/516523/  (pkovar, 16:16:20)

* OpenStack Summit Sydney  (pkovar, 16:30:42)
  * Quite a few docs-related sessions scheduled  (pkovar, 16:30:55)
  * Installation Guides and Tutorials Updates and Testing  (pkovar,
16:31:03)
  * LINK:

https://www.openstack.org/summit/sydney-2017/summit-schedule/events/20448/installation-guides-and-tutorials-updates-and-testing
(pkovar, 16:31:09)
  * Docs - Project Update  (pkovar, 16:31:16)
  * LINK:

https://www.openstack.org/summit/sydney-2017/summit-schedule/events/20373/docs-project-update
(pkovar, 16:31:21)
  * Docs/i18n - Project Onboarding  (pkovar, 16:31:26)
  * LINK:

https://www.openstack.org/summit/sydney-2017/summit-schedule/events/20550/docsi18n-project-onboarding
(pkovar, 16:31:31)
  * Ops Guide Transition and Maintenance  (pkovar, 16:31:35)
  * LINK:

https://www.openstack.org/summit/sydney-2017/summit-schedule/events/20446/ops-guide-transition-and-maintenance
(pkovar, 16:31:40)
  * Documentation and relnotes, what do you miss?  (pkovar, 16:31:45)
  * LINK:

https://www.openstack.org/summit/sydney-2017/summit-schedule/events/20468/documentation-and-relnotes-what-do-you-miss
(pkovar, 16:31:50)
  * How Zanata powers upstream collaboration with OpenStack
internationalization  (pkovar, 16:31:55)
  * LINK:

https://www.openstack.org/summit/sydney-2017/summit-schedule/events/20007/how-zanata-powers-upstream-collaboration-with-openstack-internationalization
(pkovar, 16:31:59)

* sitemap automation suggestions  (pkovar, 16:39:07)
  * LINK:
http://lists.openstack.org/pipermail/openstack-dev/2017-October/123228.html
(pkovar, 16:39:11)

* Bug Triage Team  (pkovar, 16:40:29)
  * LINK: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams
(pkovar, 16:40:34)

* PDF builds  (pkovar, 16:42:29)
  * LINK: https://review.openstack.org/#/c/509297/  (pkovar, 16:42:34)

* Open discussion  (pkovar, 16:45:05)
  * LINK: https://review.openstack.org/#/c/512136/  (chason, 16:46:13)
  * cores, if you are available, please review  (pkovar, 16:47:51)
  * LINK: https://review.openstack.org/#/c/512136/  (pkovar, 16:47:59)
  * LINK: https://docs.openstack.org/pike/deploy/ the OSA link is still
not working for me  (eumel8, 16:50:23)



Meeting ended at 16:55:59 UTC.



People present (lines said)
---

* pkovar (116)
* AJaeger (17)
* chason (13)
* eumel8 (6)
* ianychoi (4)
* openstack (3)



Generated by `MeetBot`_ 0.1.4

__
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] [docs] Documentation new meeting time - Wednesday at 16:00 UTC

[Petr Kovar]

Hi all,

Based on the input provided by the docs community, we are changing the docs
meeting day from Thursday to Wednesday. Another change is that we'll
meet in #openstack-doc. The time of the day remains the same.

To reiterate, we'll meet tomorrow, 1st November at 16:00 UTC in
#openstack-doc.  

For more details, and the agenda, see the meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Thank you,
pk

__
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] [docs] Request for docs team vision review (was: Evidence of Success)

[Petr Kovar]

Hi all,

Changing the subject line for greater visibility.

The docs team would appreciate it if more people from the community
could provide feedback on our brand new 2017/2018 docs team vision document
here:

https://review.openstack.org/#/c/514779/

If the future of OpenStack documentation is of interest to you, please have
a look and let us know what you think. This is a great chance to provide
input on what you think the OpenStack docs community should focus on in the
next 12 months or so.

Thank you,
pk


On Fri, 27 Oct 2017 16:20:27 +0200
Petr Kovar <pko...@redhat.com> wrote:

> On Tue, 17 Oct 2017 17:27:10 +0200
> Petr Kovar <pko...@redhat.com> wrote:
> 
> > Thanks for your feedback, everybody. I made some more edits to the
> > document and tried to address the remaining comments left in the etherpad.
> > 
> > I think the current revision of the doc provides enough details on
> > the metrics and goals, so it should be ready to be added to
> > https://docs.openstack.org/doc-contrib-guide/ as an official project doc.
> > Let us know if you have more comments. 
> 
> Just a quick update that a final review of the vision document can be found
> here:
> 
> https://review.openstack.org/#/c/514779/
> 
> Would be good to get move votes from the docs team and the community,
> so please have a look.
> 
> Thanks,
> pk
> 
> __
> 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


-- 
Petr Kovar
Sr. Technical Writer | Customer Content Services
Red Hat Czech, Brno

__
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] [OpenStack-docs] [docs] Docs meeting time? (was: Documentation meeting Thursday)

[Petr Kovar]

Thanks for voting, everybody. There is a strong preference to move the
meeting time to 16:00 UTC Mon or Wed, which seems to work for everybody
who voted.

http://whenisgood.net/qtqbz52/results/ptgfrap

Let's have our next week's docs meeting on Wednesday, 1st November, 16:00
UTC and see how that goes. If you have any objections, please let me know.

Cheers,
pk


On Fri, 20 Oct 2017 18:33:46 +0200
Petr Kovar <pko...@redhat.com> wrote:

> Chason, 
> 
> Thanks for bringing this up. I definitely don't want contributors from Asia
> to feel excluded. We discussed it in the docs meeting yesterday and it's
> clear that finding a meeting time that would work for Asia, Europe and
> America is a bit difficult, to say the least. 
> 
> Anyhow, I went ahead and I set up a poll to better understand what are
> people's preferences wrt meeting time:
> 
> http://whenisgood.net/qtqbz52
> 
> All, if you could indicate your time preference, that would be appreciated.
> 
> Results will appear here:
> 
> http://whenisgood.net/qtqbz52/results/ptgfrap
> 
> Thanks,
> pk
> 
> 
> On Thu, 19 Oct 2017 20:47:12 +0800
> Chason <chason.c...@foxmail.com> wrote:
> 
> > Hi Petr,
> > 
> > Is there any chance the meeting could be moved earlier one so Asian can 
> > make it?
> > Thursday at 16:00 UTC is Friday at 1:00 here.
> > 
> > Thanks,
> > 
> > Chason
> > 
> > > 在 2017年10月19日，下午8:00，openstack-docs-requ...@lists.openstack.org 写道：
> > > 
> > > Send OpenStack-docs mailing list submissions to
> > >   openstack-d...@lists.openstack.org
> > > 
> > > To subscribe or unsubscribe via the World Wide Web, visit
> > >   http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> > > or, via email, send a message with subject or body 'help' to
> > >   openstack-docs-requ...@lists.openstack.org
> > > 
> > > You can reach the person managing the list at
> > >   openstack-docs-ow...@lists.openstack.org
> > > 
> > > When replying, please edit your Subject line so it is more specific
> > > than "Re: Contents of OpenStack-docs digest..."
> > > 
> > > 
> > > Today's Topics:
> > > 
> > >   1. [docs] Documentation meeting Thursday (Petr Kovar)
> > > 
> > > 
> > > --
> > > 
> > > Message: 1
> > > Date: Wed, 18 Oct 2017 15:07:39 +0200
> > > From: Petr Kovar <pko...@redhat.com>
> > > To: openstack-d...@lists.openstack.org
> > > Cc: openstack-dev@lists.openstack.org
> > > Subject: [OpenStack-docs] [docs] Documentation meeting Thursday
> > > Message-ID: <20171018150739.28a243fd1691f243c3002...@redhat.com>
> > > Content-Type: text/plain; charset=US-ASCII
> > > 
> > > Hi all,
> > > 
> > > The docs meeting will continue tomorrow, Thursday at 16:00 UTC in
> > > #openstack-meeting, as scheduled. For more details, and the agenda, see 
> > > the meeting page:
> > > 
> > > https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
> > > 
> > > Cheers,
> > > pk
> > > 
> > > 
> > > 
> > > --
> > > 
> > > Subject: Digest Footer
> > > 
> > > ___
> > > OpenStack-docs mailing list
> > > openstack-d...@lists.openstack.org
> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> > > 
> > > 
> > > --
> > > 
> > > End of OpenStack-docs Digest, Vol 64, Issue 9
> > > *
> > 
> > 
> > 
> > 
> > ___
> > OpenStack-docs mailing list
> > openstack-d...@lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 
> ___
> OpenStack-docs mailing list
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


-- 
Petr Kovar
Sr. Technical Writer | Customer Content Services
Red Hat Czech, Brno

__
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] [docs] Evidence of Success

[Petr Kovar]

On Tue, 17 Oct 2017 17:27:10 +0200
Petr Kovar <pko...@redhat.com> wrote:

> Thanks for your feedback, everybody. I made some more edits to the
> document and tried to address the remaining comments left in the etherpad.
> 
> I think the current revision of the doc provides enough details on
> the metrics and goals, so it should be ready to be added to
> https://docs.openstack.org/doc-contrib-guide/ as an official project doc.
> Let us know if you have more comments. 

Just a quick update that a final review of the vision document can be found
here:

https://review.openstack.org/#/c/514779/

Would be good to get move votes from the docs team and the community,
so please have a look.

Thanks,
pk

__
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] [docs] Docs meeting time? (was: Documentation meeting Thursday)

[Petr Kovar]

Chason, 

Thanks for bringing this up. I definitely don't want contributors from Asia
to feel excluded. We discussed it in the docs meeting yesterday and it's
clear that finding a meeting time that would work for Asia, Europe and
America is a bit difficult, to say the least. 

Anyhow, I went ahead and I set up a poll to better understand what are
people's preferences wrt meeting time:

http://whenisgood.net/qtqbz52

All, if you could indicate your time preference, that would be appreciated.

Results will appear here:

http://whenisgood.net/qtqbz52/results/ptgfrap

Thanks,
pk


On Thu, 19 Oct 2017 20:47:12 +0800
Chason <chason.c...@foxmail.com> wrote:

> Hi Petr,
> 
> Is there any chance the meeting could be moved earlier one so Asian can make 
> it?
> Thursday at 16:00 UTC is Friday at 1:00 here.
> 
> Thanks,
> 
> Chason
> 
> > 在 2017年10月19日，下午8:00，openstack-docs-requ...@lists.openstack.org 写道：
> > 
> > Send OpenStack-docs mailing list submissions to
> > openstack-d...@lists.openstack.org
> > 
> > To subscribe or unsubscribe via the World Wide Web, visit
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> > or, via email, send a message with subject or body 'help' to
> > openstack-docs-requ...@lists.openstack.org
> > 
> > You can reach the person managing the list at
> > openstack-docs-ow...@lists.openstack.org
> > 
> > When replying, please edit your Subject line so it is more specific
> > than "Re: Contents of OpenStack-docs digest..."
> > 
> > 
> > Today's Topics:
> > 
> >   1. [docs] Documentation meeting Thursday (Petr Kovar)
> > 
> > 
> > --
> > 
> > Message: 1
> > Date: Wed, 18 Oct 2017 15:07:39 +0200
> > From: Petr Kovar <pko...@redhat.com>
> > To: openstack-d...@lists.openstack.org
> > Cc: openstack-dev@lists.openstack.org
> > Subject: [OpenStack-docs] [docs] Documentation meeting Thursday
> > Message-ID: <20171018150739.28a243fd1691f243c3002...@redhat.com>
> > Content-Type: text/plain; charset=US-ASCII
> > 
> > Hi all,
> > 
> > The docs meeting will continue tomorrow, Thursday at 16:00 UTC in
> > #openstack-meeting, as scheduled. For more details, and the agenda, see the 
> > meeting page:
> > 
> > https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
> > 
> > Cheers,
> > pk
> > 
> > 
> > 
> > --
> > 
> > Subject: Digest Footer
> > 
> > ___
> > OpenStack-docs mailing list
> > openstack-d...@lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> > 
> > 
> > --
> > 
> > End of OpenStack-docs Digest, Vol 64, Issue 9
> > *
> 
> 
> 
> 
> ___
> OpenStack-docs mailing list
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

__
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] [OpenStack-docs] [docs] Documentation meeting Thursday

[Petr Kovar]

Below are the meeting minutes from yesterday's docs team meeting.

Because we ran out of time (too many items to cover!), the conversation
about site map automation continued in #openstack-doc after the meeting:

http://eavesdrop.openstack.org/irclogs/%23openstack-doc/%23openstack-doc.2017-10-19.log.html

===
#openstack-meeting: docteam
===


Meeting started by pkovar at 16:01:09 UTC.  The full logs are available
at
http://eavesdrop.openstack.org/meetings/docteam/2017/docteam.2017-10-19-16.01.log.html
.



Meeting summary
---

* Docs meeting time?  (pkovar, 16:06:12)
  * ACTION: pkovar to initiate a mtg time poll  (pkovar, 16:16:13)
  * reconsider removing the docs ML  (pkovar, 16:23:05)
  * decisions to be made in ML (-dev, preferably)  (pkovar, 16:23:42)
  * consider sending status updates  (pkovar, 16:24:39)

* Docs team vision document  (pkovar, 16:26:24)
  * LINK:
https://etherpad.openstack.org/p/docs-i18n-ptg-queens-mission-statement
(pkovar, 16:26:34)
  * LINK: https://docs.openstack.org/doc-contrib-guide/  (pkovar,
16:27:58)
  * ACTION: pkovar to add the vision doc to doc contrib guide  (pkovar,
16:30:50)

* Docs retention policy changes  (pkovar, 16:31:29)
  * LINK: https://review.openstack.org/#/c/507629  (pkovar, 16:31:47)
  * LINK: https://review.openstack.org/#/c/491868/ to derive series name
by the theme  (pkovar, 16:36:38)
  * coordinate with tonyb and the stable team to avoid closing stable
branches before adding badges to docs  (pkovar, 16:39:37)
  * LINK:
https://etherpad.openstack.org/p/docs-i18n-ptg-queens-release-badges
(jamesmcarthur, 16:40:20)
  * LINK:
https://etherpad.openstack.org/p/docs-i18n-ptg-queens-release-badges
(pkovar, 16:40:43)

* Contributor Portal  (pkovar, 16:43:46)
  * LINK:
http://lists.openstack.org/pipermail/openstack-dev/2017-October/123740.html
(pkovar, 16:44:03)
  * LINK: https://www.openstack.org/community/  (pkovar, 16:44:50)
  * LINK: https://docs.openstack.org/contributors  (pkovar, 16:45:01)
  * LINK: https://docs.openstack.org/doc-contrib-guide/  (pkovar,
16:45:13)

* sitemap automation suggestions  (pkovar, 16:47:39)
  * LINK:
http://lists.openstack.org/pipermail/openstack-dev/2017-October/123228.html
(pkovar, 16:47:48)
  * ACTION: mguiney volunteered to help with sitemap automation, thanks
(pkovar, 16:57:35)



Meeting ended at 17:00:10 UTC.



Action items, by person
---

* mguiney
  * mguiney volunteered to help with sitemap automation, thanks
* pkovar
  * pkovar to initiate a mtg time poll
  * pkovar to add the vision doc to doc contrib guide



People present (lines said)
---

* pkovar (93)
* dhellmann (58)
* jamesmcarthur (32)
* eumel8 (8)
* mguiney (8)
* bsilverman (7)
* openstack (4)
* thingee (1)



Generated by `MeetBot`_ 0.1.4

__
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] [docs] Documentation meeting Thursday

[Petr Kovar]

Hi all,

The docs meeting will continue tomorrow, Thursday at 16:00 UTC in
#openstack-meeting, as scheduled. For more details, and the agenda, see the 
meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] [docs][ptls][all] documentation retention policy changes

[Petr Kovar]

On Thu, 28 Sep 2017 12:51:18 -0400
Doug Hellmann  wrote:

> At the Queens PTG in Denver the documentation team members present
> discussed a new retention policy for content published to
> docs.openstack.org. I have a spec up for review to document that
> policy and the steps needed to implement it. This policy will affect
> all projects, now that most of the documentation is managed by
> project teams. Please take a few minutes to review it, or at the
> very least have your documentation team liaison do so.
> 
> https://review.openstack.org/#/c/507629

We've just approved this spec. Thanks Doug for putting this together!

With this spec approved, we'll no longer delete EOL docs and will also
restore (some of the) Mitaka content back to docs.openstack.org/mitaka.

We still need help with updating the Ocata branch and (writing
a spec) and implementing badges to warn users about unsupported content. If
you can help with these, please let us know (and see the thread Flagging
deprecated releases started by Jimmy).

Cheers,
pk

__
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] [docs] Evidence of Success

[Petr Kovar]

..@openstack.org>
> > > October 4, 2017 at 10:46 AM
> > > I've made a bit of progress on the collaborative vision for the Docs 
> > > team: 
> > > https://docs.google.com/document/d/1Xy78CnmnKlQ7SbR1XewqgrUdGe7DqnKAGYw_9aj5Ndg/edit#
> > >  
> > >
> > >
> > > This still needs plenty of work, but I wanted to put out what we have 
> > > so we can start to get some feedback from other members of the Docs 
> > > team. The Use Cases section in particular was really vast and hard to 
> > > cut down into prose without getting too detailed.
> > >
> > > Welcome your feedback and input!
> > >
> > > Thanks,
> > > Jimmy
> > >
> > >
> > >
> > > __
> > >  
> > >
> > > 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


-- 
Petr Kovar
Sr. Technical Writer | Customer Content Services
Red Hat Czech, Brno

__
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] [docs] sitemap automation suggestions

[Petr Kovar]

As for logging 301s, 302s and 404s and the scope, I don't think we are
interested in checking EOL content for those.

As we are about to approve https://review.openstack.org/#/c/507629/, we
also want everybody to understand broken links found in EOL content won't
be fixed, since no content updates to EOL content will be provided.

Cheers,
pk


On Thu, 5 Oct 2017 22:51:31 -0400 (EDT)
"me...@openstack.org"  wrote:

> Hello all!
> 
> As you may be aware, sitemaps generation for docs.openstack.org is currently 
> done via a manually triggered scrapy process. It currently also scrapes the 
> entirety of docs.openstack.org, making processing slow. In order to improve 
> the efficiency of this process, I would like to propose the following updates 
> to the sitemap generation toolkit:
> * keep track (in logs) of 301s, 302s, and 404s,
> * automatic pull of supported releases,
> * cron-managed automatic updates, and
> * setup of Google Webmaster tools (https://www.google.com/webmasters/) 
> * a few style cleanups
> 
> Beyond this, implementing more targeted crawling would improve the processing 
> speed and scope massively. This is, however, a bit of a complicated matter, 
> as it requires us to decide what, exactly, defines scope relevence, in order 
> to limit the crawl domain.
> 
> These are, of course, only our precursory findings. and we would love to hear 
> some feedback about alternate methods and possible tricky aspects of the 
> suggested changes. What do you think? Let us know!
> 
> 
> __
> 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] Contributor Portal PTG Recap

[Petr Kovar]

Hi all,

Just a quick update on how the contributor portal project will be
organized.

We created a new subteam under the Documentation Project.
This subteam (specialty team), led by Mike, will maintain the
portal repo openstack/contributor-guide.

Patches addressing this have been merged:

https://review.openstack.org/#/q/Ib8062210854e1979aa1f56bd7c0f5af8e578decc

Thanks,
pk


On Fri, 22 Sep 2017 11:13:46 -0700
Mike Perez  wrote:

> # Contributor Portal Next Steps
> 
> ## Landing Page Mock ups
> * Current mock up:
> https://drive.google.com/file/d/0BxMh9oiou2xMLVRvRWRFVklHa2c/view
> * Limited click through mock up:
> https://invis.io/CSDEZTBDJ#/252645774_Landing
> 
> ## Todo
> - [ ] thingee: A proposal for the *second level* of what the landing page
> shows.
> - [ ] thingee: Follow up with the Wes and Jimmy at the OpenStack Foundation
> for design assistance.
> 
> ## Communication To The Community
> * [Initial
> email](http://lists.openstack.org/pipermail/openstack-dev/2017-June/118877.html)
> * [Initial full
> thread](http://lists.openstack.org/pipermail/openstack-dev/2017-June/thread.html#118877)
> 
> ## Highlights from PTG session
> [OpenStack Etherpad](https://etherpad.openstack.org/p/contributor-portal)
> 
> ### TLDR (big changes from discussion)
> * Instead of all team on-boarding documentation living in a central
> repository, it will still remain with the individual teams to maintain in
> their own repository. General documentation (e.g. git, creating accounts,
> gerrit setup, etc) will still live in this central repo. If you choose to
> contribute by code for example and you pick a project, it will take you
> through our general documentation, then the project’s specific documentation.
> * This could lead to inconsistencies in documentation design? Confusion
> for the reader being sent to different pages?
> 
> ### General
> * We can’t go based off services. Not everything people are contributing
> to is a service, so they won't have anything corresponding in the
> [service type authority
> repo](http://git.openstack.org/cgit/openstack/service-types-authority/tree/service-types.yaml).
> There might be a field in projects.yaml that can help with this.
> * Remind Thierry on the service type authority repo for
> grouping/mapping project.
> * Videos were considered, but they’re hard to keep up-to-date.
> Previous Documentation PTL Alexandra Settle expressed that even
> screenshots can get out of date real fast. 
> * Generate some kind of crash-course / cheatsheet content for people
> who are used to GitHub but not familiar with Gerrit. Aspiers
> volunteered for this and made this first pass [ethercalc
> sheet](https://ethercalc.openstack.org/github-gerrit).
> * Translation team needs to be included
> * Provide documentation with how to edit the landing page, since the
> source is being hosted on github (there are transition discussions in
> place with the infra team and Jimmy)
> * Help projects with creating their own contributor guides if they
> need to. Think of something like Cookie cutter for setting up the
> scaffolding for a new OpenStack project, but getting projects
> contributor guides going.
> 
> ### Upstream Institute
> Attendees of the session we’re more in favor of projects keeping
> their specific documentation owned in their repositories. As learned
> from the centralize documentation problem
> [1](http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html)
> [2](https://doughellmann.com/blog/2017/08/24/stop-working-so-hard-scaling-open-source-community-practices/)
> [3](https://governance.openstack.org/tc/reference/top-5-help-wanted.html#documentation-owners),
> this is a good move. Upstream institute would then use whatever
> general documentation is provided. If people get past that, we could
> even suggest on-boarding to one of the [top 5 most wanted
> help](https://governance.openstack.org/tc/reference/top-5-help-wanted.html)!
> 
> ### User Committee
> Lauren Sell worked with Melvin and others from the user committee to get their
> requirements and perspective on the project. Here's an ether pad:
> https://etherpad.openstack.org/p/contributor-portal-user-section
> 
> ### Mock Up Feedback
> * Having the service types is great, but on the next level it would
> be good to express the code name with a description of what the
> project does.
> * Combine in events OpenStack day, meetups, forum, ptg, etc.
> (emphasize on in person thing)
> 
> ### Bikeshed
> * A word that combines code and documentation ("team(s)" was already
> rejected)
> 
> -- 
> Mike Perez

__
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] [docs][ptls][install] Install guide vs. tutorial

[Petr Kovar]

On Wed, 4 Oct 2017 09:59:34 -0500
Jay S Bryant  wrote:

> 
> 
> On 9/29/2017 3:27 PM, Doug Hellmann wrote:
> > Excerpts from Petr Kovar's message of 2017-09-29 21:09:02 +0200:
> >> On Tue, 26 Sep 2017 18:53:04 -0500
> >> Jay S Bryant  wrote:
> >>
> >>>
> >>> On 9/25/2017 3:47 AM, Alexandra Settle wrote:
> 
>    > I completely agree consistency is more important, than bike 
>  shedding over the
>    > name :)
>    > To be honest, it would be easier to change everything to ‘guide’ 
>  – seeing as
>    > all our URLs are ‘install-guide’.
>    > But that’s the lazy in me speaking.
>    >
>    > Industry wise – there does seem to be more of a trend towards 
>  ‘guide’ rather
>    > than ‘tutorial’. Although, that is at a cursory glance.
>    >
>    > I am happy to investigate further, if this matter is of some 
>  contention to
>    > people?
>    
>    This is the first time I'm hearing about "Install Tutorial". I'm 
>  also lazy, +1
>    with sticking to install guide.
>    
>  Just to clarify: https://docs.openstack.org/install-guide/ The link is 
>  “install-guide” but the actual title on the page is “OpenStack 
>  Installation Tutorial”.
> 
>  Apologies if I haven’t been clear enough in this thread! Context always 
>  helps :P
> 
> >>> Oy!  The URL says guide but the page says tutorial?  That is even more
> >>> confusing.  I think it would be good to make it consistent and just with
> >>> guide then.  All for your laziness when it leads to consistency.  :-)
> >> Yes, this inconsistency in document naming is totally something we need
> >> to change, hopefully based on the outcome of this discussion.
> >>
> >> At the PTG, I was leaning towards "tutorial" because previously, the docs
> >> team chose that term to distinguish an installation HOWTO (describing
> >> installing a PoC environment from packages) from a more general guide on
> >> installation (possibly documenting different methods that different
> >> audiences can use).
> >>
> >> But I could go with both.
> >>
> >> Cheers,
> >> pk
> >>
> > Everyone seems rather flexible on this, so I think we just need someone
> > to pick a name.
> >
> > Using "tutorial" will involve renaming the directory containing all of
> > the content and updating the way that is published in openstack-manuals.
> >
> > Using "guide" will involve changing the contents of the documents
> > inside a few files in openstack-manuals to match where it is already
> > published, and we can do that with sed.
> >
> > My vote is to do the simple thing, and change the file contents:
> > https://review.openstack.org/508608
> >
> > Doug
> >
> +2
> 
> I think keeping it simple, if no one has strong objections, is the best 
> way to go.

Doug's patch has been approved and merged so we no longer use the word
"tutorial" in openstack-manuals. If project teams could go ahead and check
that their install docs use the correct terminology (installation guide, not
tutorial), that'd be much appreciated.

Thank you,
pk 

__
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] [docs] Documentation meeting today

[Petr Kovar]

Hi all,

The docs meeting will continue today at 16:00 UTC in #openstack-meeting, as
scheduled. For more details, and the agenda, see the meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] [docs][ptls][install] Install guide vs. tutorial

[Petr Kovar]

On Tue, 26 Sep 2017 18:53:04 -0500
Jay S Bryant  wrote:

> 
> 
> On 9/25/2017 3:47 AM, Alexandra Settle wrote:
> >   
> >  > I completely agree consistency is more important, than bike shedding 
> > over the
> >  > name :)
> >  > To be honest, it would be easier to change everything to ‘guide’ – 
> > seeing as
> >  > all our URLs are ‘install-guide’.
> >  > But that’s the lazy in me speaking.
> >  >
> >  > Industry wise – there does seem to be more of a trend towards 
> > ‘guide’ rather
> >  > than ‘tutorial’. Although, that is at a cursory glance.
> >  >
> >  > I am happy to investigate further, if this matter is of some 
> > contention to
> >  > people?
> >  
> >  This is the first time I'm hearing about "Install Tutorial". I'm also 
> > lazy, +1
> >  with sticking to install guide.
> >  
> > Just to clarify: https://docs.openstack.org/install-guide/ The link is 
> > “install-guide” but the actual title on the page is “OpenStack Installation 
> > Tutorial”.
> >
> > Apologies if I haven’t been clear enough in this thread! Context always 
> > helps :P
> >
> Oy!  The URL says guide but the page says tutorial?  That is even more 
> confusing.  I think it would be good to make it consistent and just with 
> guide then.  All for your laziness when it leads to consistency.  :-)

Yes, this inconsistency in document naming is totally something we need
to change, hopefully based on the outcome of this discussion.

At the PTG, I was leaning towards "tutorial" because previously, the docs
team chose that term to distinguish an installation HOWTO (describing
installing a PoC environment from packages) from a more general guide on
installation (possibly documenting different methods that different
audiences can use).

But I could go with both.

Cheers,
pk

__
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] [docs][i18n][ptg] Denver PTG Summary for Docs (and i18n)

[Petr Kovar]

Hi all,

Just wanted to share a few notes and a brief summary of what happened in
Denver last week, during the Project Team Gathering, in docs and i18n
shared sessions.

We had a fairly good attendance of 5 to 15 ppl during the first two
days. A number of people primarily working on other projects showed up in
our sessions to chat about common issues and plans. On the other hand, many
of our cores couldn't attend, though I'm hoping if PTG comes closer to
Europe, the attendance will improve.

On a related note, we also welcomed new cores to the team and the Denver
PTG was an opportunity for some of us to meet face to face for the first
time.

The overall schedule for all our sessions with some comments can be found at
https://etherpad.openstack.org/p/docs-i18n-ptg-queens, there's also
https://etherpad.openstack.org/p/doc-future-problems with a more detailed
discussion of some of the items.

To summarize what I found most important:

VISION

We spent a lot of time discussing a new vision document for the docs team,
based on the updated docs team mission statement
(https://review.openstack.org/#/c/499556/). A working draft is available
here:

https://etherpad.openstack.org/p/docs-i18n-ptg-queens-mission-statement

In the coming weeks, we'll transform those notes into a final draft and
share it with the broader community for input.

The next step after this would be to update/rework
https://governance.openstack.org/tc/reference/tags/docs_follows-policy.html.

EOL DOCS AVAILABILITY

Discussed addressing numerous issues related to publishing EOL docs and our
docs retention policy, based on community feedback and many requests. The
plan is to write a retention policy docs spec, resurrect Mitaka docs and add
badges to clearly identify unsupported content, among other things.

HA GUIDE

Work will continue on the guide per the previous plans.

ARCHITECTURE GUIDE

From Pike, this guide is frozen. Patches still welcome.

OPENSTACK-MANUALS BUGS

To be moved to appropriate projects, if applicable.

CONFIG DOCS

Discussed with several teams, particularly cinder, how to generate
config tables using oslo_config.sphinxext.

REDESIGNING DOCS SITE

A couple of improvements to adjust the site content structure and
overall design was discussed, such as tweaking lists of projects, linking
from series subpages back to the top page, install vs. deployment pages,
linking to projects with no stable branches, redoing our sitemap, switching
to SCSS, improving HTML semantics, etc.

DOCS TOOLING

Doug kindly offered the team and the community to give a presentation
about updated docs tooling:

https://etherpad.openstack.org/p/doc-tool-lunch-and-learn

We'll turn this into a proper doc and share with everybody.

INSTALL GUIDES TESTING

A couple of people and teams showed interest in testing the Pike install
guides (common content + minimal deployment services). To track this
activity, we'll use this wiki page:

https://wiki.openstack.org/wiki/Documentation/PikeDocTesting

TRANSLATIONS

Discussed generating multiple PO files for docs
migrated to project repos, to make translators' lives easier.

THAT'S IT?

Please add to the list if I missed anything important, particularly for
i18n.

Thank you to everybody who attended the sessions, and in particular to Alex
who took most of the notes. I think this PTG was very productive, full of
energy, and intense!

Cheers,
pk

__
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] [ptg][i18n][doc] Install Guides Testing

[Petr Kovar]

Hi all,

Just a reminder that we are meeting tomorrow at 9 am in Colorado Ballroom C
for an Install Guides testing session.

Interested? Sign up here:
https://etherpad.openstack.org/p/docs-i18n-ptg-queens

See you there!
pk


On Fri, 01 Sep 2017 09:47:18 +0200
Frank Kloeker  wrote:

> Good morning,
> 
> it's only a week to the next PTG in Denver. I would like to invite you 
> to visit our project etherpad on [1]. We as I18n team are together with 
> the Doc team in the same room and we share also our planning on the 
> etherpad.
> Monday morning we reserved some time to say "Hello" to everybody. Take 
> the chance to meet us and let me know if you have some topics for the 
> translation team.
> 
> kind regards
> 
> Frank (eumel8)
> PTL I18n
> 
> [1] https://etherpad.openstack.org/p/docs-i18n-ptg-queens
> 
> ___
> OpenStack-docs mailing list
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


__
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] [ptg][docs][i18n] Team lunch today

[Petr Kovar]

Hi all,

For those attending the PTG in Denver, let's have team lunch today. We'd
meet at 12 pm in front of the PTG registration desk. 

See you there,
pk

__
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] [docs] Documentation meeting Thursday

[Petr Kovar]

Hi all,

The docs meeting will continue tomorrow, Thursday at 16:00 UTC in
#openstack-meeting, as scheduled. For more details, and the agenda, see the
meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] [docs] [ptls] Install guide testing

[Petr Kovar]

oard[1] that we still have quite a few open reviews and a few
> > missing pages. At this point, the missing docs will need to be backported to
> > the stable/pike branches for those projects.
> > Let me know if you need help approving things in the stable branches.
> > 
> > [1] https://doughellmann.com/doc-migration/
> > 
> > __
> > 
> > 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


-- 
Petr Kovar
Sr. Technical Writer | Customer Content Services
Red Hat Czech, Brno

__
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] [docs] Re: Install guide testing

[Petr Kovar]

On Fri, 25 Aug 2017 15:40:07 +0200
Roger Luethi wrote:

> I don't know what will get changed or created until the release, but
> what I can find right now in terms of installation instructions is this:
> 
> https://docs.openstack.org/pike/install/
> 
> leading to the "OpenStack Installation Tutorial":
> 
> https://docs.openstack.org/install-guide/
> 
> plus many project-specific instructions:
> 
> https://docs.openstack.org//pike/install/
> 
> The OpenStack Installation Tuturial is labelled "Installation Guide
> 15.0", same as Ocata (Newton was 0.1). The URL is not versioned, even
> though there will be changes between releases (the instructions for
> enabling the OpenStack repository are updated every release, and there
> are bound to be other differences). I wonder how that will be handled
> in the future.

So the install guide is not versioned from Pike on, by design, and
https://review.openstack.org/#/c/498197/ removed version numbers from
guide labels. Should be less confusing now, I hope.
 
> I have not read all of the new "OpenStack Installation Tutorial", but
> looking at the table of contents, there seems to be a gap between
> "Environment"->"Memcached" and "Launch an instance". Where do we tell the
> readers which project-specific guides to follow, and in what order? Both
> pieces of information are rather crucial for a successful installation.

That has been addressed in https://review.openstack.org/#/c/497813/ and
again in https://review.openstack.org/#/c/498539/. We now have pointers to
project guides and information on a minimal cloud deployment included in
between "Memcached" and "Launch an instance":

https://docs.openstack.org/install-guide/openstack-services.html
 
> I expect users will find confusing that clicking the "Next" arrow on a
> distro-specific page (say, [1]) will often take them to the same page,
> just for a different distro. In the keystone install-guide, clicking on
> the Next arrow can result in skipped pages (depending on the distro,
> e.g. [2]). I realize that distro-specific instructions are not easily
> implemented with the new setup, but maybe the doc team could suggest
> a way to handle distro-specific paths for all projects.

I actually liked the keystone guide structure but I agree that following the
Next links can be confusing to users. Issues like this are totally something
we could have a closer look at the PTG, if people are available on Thu.

Sign up at https://etherpad.openstack.org/p/docs-i18n-ptg-queens.

Thanks,
pk

__
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] [docs] Documentation meeting Thursday

[Petr Kovar]

Hi all,

The docs meeting will continue tomorrow, Thursday at 16:00 UTC in
#openstack-meeting, as scheduled. For more details, and the agenda, see the
meeting page:

https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

Cheers,
pk

__
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] [docs] Updating the docs team mission statement

[Petr Kovar]

Hi all,

With the core docs suite moving from openstack-manuals to individual
project repos as per
http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html,
it's also time to update the docs team mission statement from
https://governance.openstack.org/tc/reference/projects/documentation.html.

What are everybody's thoughts on what should the new mission statement
say now that most OpenStack docs maintenance is in the hands of project
teams?

One idea is for the docs team to act as a focused group of editors and
maintain a common set of guidelines, recommended practices (style
guidelines come to mind, for instance), and requirements (such as a common
docs and publishing structure shared across projects).

Other ideas, thoughts, or comments?

Based on the feedback from the community, we plan to update
https://governance.openstack.org/tc/reference/tags/docs_follows-policy.html
too.

Thanks,
pk

__
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] [docs][ptl] Candidacy for Docs

[Petr Kovar]

Hi all,

I'd like to announce my candidacy for PTL of the docs project for Queens.

I've been active in various open source documentation and
translation projects since 2007 and started contributing to OpenStack
docs during the Mitaka cycle, both upstream and in the RDO Project.

The docs project has recently seen a significant decrease in both the
number of submitted updates and contributors, but thanks to a group of
dedicated people in the community, we've managed to come up with a clear
plan to migrate docs over to individual projects, restructure them and
reduce the scope to keep them maintainable. This is now well underway and
I'd like to help the team and the community drive and continue with this
work.

In docs, we generally like to keep it rather short and simple, so let me
summarize the main three points as follows:

Support and help drive the remaining tasks in restructuring and/or moving
content from the core docs suite.

Help establish the docs team as content editors for individual project docs
when needed or requested.

Stay open and friendly to new contributors, no matter if they are
prospective core members or drive-by docs contributors, with the
understanding that docs are a great way to get involved in the project for
both the non- and developers.

Thank you,
pk

-- 
Petr Kovar
Sr. Technical Writer | Customer Content Services
Red Hat Czech, Brno

__
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] [OpenStack-docs] [openstack-docs][dev][all] Documentation repo freeze

[Petr Kovar]

On Mon, 19 Jun 2017 15:56:35 +
Alexandra Settle  wrote:

> Hi everyone,
> 
> As of today - Monday, the 19th of June – please do NOT merge any patches into
> the openstack-manuals repository that is not related to the topic:
> “doc-migration”.
> 
> We are currently in the phase of setting up for our MASSIVE migration and we
> need to ensure that there will be minimal conflicts.
> 
> You can find all patches related to that topic here:
> https://review.openstack.org/#/q/status:open+project:openstack/openstack-manuals+branch:master+topic:doc-migration
> 
> The only other patches that should be passed is the Zanata translation 
> patches.
> 
> If there are any concerns or questions, please do not hesitate to contact 
> either
> myself or Doug Hellmann for further clarification.

Can we still merge into stable branches? As the migration only affects
content in master, I think there's no need to freeze stable branches. 

Thanks,
pk

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

[Petr Kovar]

On Mon, 22 May 2017 09:39:09 +
Alexandra Settle  wrote:

(...)

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

First off, thanks a lot for sending this out!

If my understanding is correct, the openstack-manual repo would only store
static index pages and some configuration files? Everything under
https://github.com/openstack/openstack-manuals/tree/master/doc would be
moved to project repos? 

The installation guide is special in that project-specific in-tree guides
still depend on common content that currently lives in openstack-manuals.
Where would that common content go, then?

This includes installation guide sections such as:

https://docs.openstack.org/ocata/install-guide-rdo/overview.html
https://docs.openstack.org/ocata/install-guide-rdo/environment.html
https://docs.openstack.org/ocata/install-guide-rdo/launch-instance.html

Also, unlike the openstack-manual's installation guide content, the in-tree
guides do not use conditional content for different distributions. I assume
individual projects would need to maintain separate common content for
each distribution?

(...)

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

If the intention here is to make the content more visible to developers who
work in project repos, then separating the content to a different repo
kind of goes against that idea, I think.

Cheers,
pk

__
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