Re: [openstack-dev] [OpenStack-docs] [docs][release][ptl] Adding docs to the release schedule

[Darren Chan]

On 2/3/17 5:07 am, Alexandra Settle wrote:


On 3/1/17, 5:58 PM, "John Dickinson"  wrote:

 
 
 On 1 Mar 2017, at 9:52, Alexandra Settle wrote:
 
 > Hi everyone,

 >
 > I would like to propose that we introduce a “Review documentation” 
period on the release schedule.
 >
 > We would formulate it as a deadline, so that it fits in the schedule and 
making it coincide with the RC1 deadline.
 >
 > For projects that are not following the milestones, we would translate 
this new inclusion literally, so if you would like your project to be documented 
at docs.o.o, then doc must be introduced and reviewed one month before the branch 
is cut.
 
 Which docs are these? There are several different sets of docs that are hosted on docs.o.o that are managed within a project repo. Are you saying those won't get pushed to

 docs.o.o if they are patched within a month of the cycle release?

The only sets of docs that are published on the docs.o.o site that are managed 
in project-specific repos is the project-specific installation guides. That 
management is entirely up to the team themselves, but I would like to push for 
the integration of a “documentation review” period to ensure that those teams 
are reviewing their docs in their own tree.

This is a preferential suggestion, not a demand. I cannot make you review your 
documentation at any given period.

The ‘month before’ that I refer to would be for introduction of documentation 
and a review period. I will not stop any documentation being pushed to the repo 
unless, of course, it is untested and breaks the installation process.
 
 
 >

 > In the last week since we released Ocata, it has become increasingly 
apparent that the documentation was not updated from the development side. We were 
not aware of a lot of new enhancements, features, or major bug fixes for certain 
projects. This means we have released with incorrect/out-of-date documentation. 
This is not only an unfortunately bad reflection on our team, but on the project 
teams themselves.
 >
FYI, there's a few bugs for the Configuration Reference mentioning 
options for some services require updating. I've gone through the doc 
and created additional bugs and included the relevant PTL and docs liaison.

 > The new inclusion to the schedule may seem unnecessary, but a lot of 
people rely on this and the PTL drives milestones from this schedule.
 >
 > From our side, I endeavor to ensure our release managers are working 
harder to ping and remind doc liaisons and PTLs to ensure the documentation is 
appropriately updated and working to ensure this does not happen in the future.
 >
 > Thanks,
 >
 > Alex
 
 
 > __

 > OpenStack Development Mailing List (not for usage questions)
 > Unsubscribe: 
openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
 > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
 


___
OpenStack-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] [Openstack-docs] [docs] [arch-guide] Architecture Design Guide plan for Pike

[Darren Chan]

Hi everyone,

Just an update on the draft Architecture Design Guide.

For Ocata, we reorganized some migrated content from the current Arch 
Guide and Ops Guide, and updated the compute and networking sections in 
the Design chapter. It is currently published at 
http://docs.openstack.org/draft/arch-design-draft/.


As discussed at the PTG (1), our plan for Pike:

1. Writing the Design chapter is the highest priority.  The goal to
   complete the networking and storage sections first, then work on the
   remaining sections and chapters.
2. Create a bug report for each task, describing what information
   should be covered to complete the task.
3. Develop a use case template which will be applied to all
   architecture use cases in the guide.
4. Remove the architecture content from the Ops Guide since it has been
   migrated and integrated into the draft Arch Guide.
5. Remove the current Arch Guide and publish the draft Arch Guide to
   docs.openstack.org.

Our plans are also documented in the spec: 
https://review.openstack.org/#/c/436747/. I would really appreciate some 
reviews and comments.


Overhauling the guide has been ongoing for a few release cycles due to 
lack of contributors. We would like to make good progress for Pike, so 
if you are interested in getting involved, please reach out to me or Ben 
Silverman.


Thanks!

Darren

 (1) https://etherpad.openstack.org/p/docs-i18n-ptg-pike

__
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-operators] [docs][upgrades] time to add official docs for upgrading services?

[darren chan]

No problem :) I simplified the spec to be more realistic about what we can 
achieve for Ocata.
https://review.openstack.org/#/c/394261/
 

On Friday, 18 November 2016, 23:53, Steve Martinelli 
<s.martine...@gmail.com> wrote:
 

 
On Thu, Nov 17, 2016 at 11:04 PM, darren chan <dazzac...@yahoo.com.au> wrote:

Good timing, I was about to send a follow-up email about this spec.
I agree, this content needs to be more visible, which is why the spec proposed 
to move upgrade notes to the Upgrades chapter in the Operations Guide. However, 
it seems like the general consensus is to keep content in project repos because 
it is more likely to be maintained there. 


Considering the Ocata development cycle is pretty short, we've already 
established our docs deliverables, and other projects are still developing 
upgrade notes, would links to the upgrade notes in the Ops Guide suffice in the 
interim? We can then propose and plan a better solution for Pike, such as 
in-tree official guides? 
Thoughts? 


The project teams will always use the maintenance argument. But I understand 
your concern, and in my initial draft to the mailing list i was going to voice 
a similar statement. Maybe wait until teams have fleshed out their various 
supported upgrade strategies? 

 
Darren

On Friday, 18 November 2016, 13:33, Lana Brindley 
<openst...@lanabrindley.com> wrote:
 

 Isn't that more or less what this is?

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



Yup! Thanks for reading my mind docs team :)

   __
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-operators] [docs][upgrades] time to add official docs for upgrading services?

[darren chan]

Good timing, I was about to send a follow-up email about this spec.
I agree, this content needs to be more visible, which is why the spec proposed 
to move upgrade notes to the Upgrades chapter in the Operations Guide. However, 
it seems like the general consensus is to keep content in project repos because 
it is more likely to be maintained there. 
Considering the Ocata development cycle is pretty short, we've already 
established our docs deliverables, and other projects are still developing 
upgrade notes, would links to the upgrade notes in the Ops Guide suffice in the 
interim? We can then propose and plan a better solution for Pike, such as 
in-tree official guides? 
Thoughts? 
Darren

On Friday, 18 November 2016, 13:33, Lana Brindley 
 wrote:
 

 Isn't that more or less what this is?

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

L

On 18/11/16 11:36, Steve Martinelli wrote:
> In the keystone docs we have notes about how to upgrade between releases [1], 
> so does the nova team [2].
> 
> Is it time we create an official guides to [3] for this subject?
> 
> [1] http://docs.openstack.org/developer/keystone/upgrading.html
> [2] http://docs.openstack.org/developer/nova/upgrade.html
> [3] http://docs.openstack.org/
> 
> 
> ___
> OpenStack-docs mailing list
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 

-- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com

___
OpenStack-docs mailing list
openstack-d...@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


   

signature.asc
Description: PGP signature
__
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] [Openstack-operators] [OpenStack-docs] [OpenStack-dev] [docs] Project upgrade notes

[darren chan]

Hi everyone,
There was an operations community discussion during the Ocata summit to include 
upgrade notes from the developer documentation in the Operations Guide. The 
spec can be reviewed here:
 https://review.openstack.org/#/c/394261/
Feedback and comments are appreciated!
Thanks,
Darren  __
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] [all] Proposal: Architecture Working Group

[darren chan]

It appears this group could assist with the Architecture Design Guide, which is 
undergoing a content restructure. We are looking for more technical 
contributors to provide guidance and contribute information to the guide. Shaun 
O'Meara has written a spec: 
https://specs.openstack.org/openstack/docs-specs/specs/newton/arch-guide-restructure.html.
        
If you are interested in helping out, contact Shilla or me, or feel free to 
join our biweekly Ops Guide/Arch Guide Specialty team meeting. For more 
details, see https://wiki.openstack.org/wiki/Documentation/OpsGuide.

Thanks!


On Saturday, 25 June 2016, 2:50, Clint Byrum  wrote:
 

 Excerpts from Zhipeng Huang's message of 2016-06-24 18:15:30 +0200:
> Hi Clint and Amrith,
> 
> Are you guys already working on the proposal ? Is there any public access
> to see the first draft ?
> 

I've started writing something up, and I hope to submit it for review
next week.

__
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