Re: [openstack-dev] [docs] Nominating Ian Y. Choi for openstack-doc-core
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
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
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
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
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
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
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?
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?
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
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
=== #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
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
On Thu, 17 May 2018 15:03:23 + Jeremy Stanley wrote: > On 2018-05-17 16:35:36 +0200 (+0200), Petr Kovar wrote: > > On Wed, 16 May 2018 17:05:15 + > > Jeremy Stanley 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
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
On Wed, 16 May 2018 17:05:15 + Jeremy Stanley 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?
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 see where the > collaboration takes us. Is a tripleo-focused quick-s
[openstack-dev] [docs] Style guide for OpenStack documentation
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?
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
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
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 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 > Date: Wednesday, May 9, 2018 at 2:13 PM > To: "OpenStack Development Mailing List (not for usage questions)" > > Cc: Petr Kovar , Jean-Philippe Evrard > > 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
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"
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
=== #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
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
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
=== #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
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
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?
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
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
On Wed, 14 Mar 2018 10:38:37 -0500 Jay S Bryant wrote: > > > On 3/14/2018 10:04 AM, Petr Kovar wrote: > > On Tue, 13 Mar 2018 18:57:24 -0500 > > Jay S Bryant 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 >>> <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 >>> <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 > >>> > >>> > >>>
Re: [openstack-dev] [First Contact][SIG] [PTG] Summary of Discussions
On Tue, 13 Mar 2018 18:57:24 -0500 Jay S Bryant 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 > <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 > <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> > > It would give me a page to craft for new users looking for
Re: [openstack-dev] [First Contact][SIG] [PTG] Summary of Discussions
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
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
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
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'.
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
=== #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
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
On Fri, 16 Feb 2018 17:49:37 +0100 Thomas Goirand wrote: > On 02/16/2018 03:42 PM, Petr Kovar wrote: > > 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? > > 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
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
=== #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
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
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
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
=== #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
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
=== #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
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
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
On Tue, 17 Oct 2017 19:15:32 +0200 Petr Kovar wrote: > 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). 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
=== #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
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
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
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
=== #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
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
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
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
All, Please consider today's meeting canceled. Thanks, pk > From: "Petr Kovar" > To: openstack-dev@lists.openstack.org > Cc: "enstack.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
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
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
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)
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 wrote: > On Tue, 17 Oct 2017 17:27:10 +0200 > Petr Kovar 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)
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 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 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 > > > 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
On Tue, 17 Oct 2017 17:27:10 +0200 Petr Kovar 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)
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 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 > > 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
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
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
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
McArthur <mailto:ji...@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
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
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
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
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
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)
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
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
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
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
inished with the migration, but I see on > > the dashboard[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
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
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
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
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
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
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
