Re: [openstack-dev] [OpenStack-docs] What's Up, Doc? 6 May 2016

2016-05-07 Thread Anne Gentle 
On Sat, May 7, 2016 at 1:51 PM, Andreas Jaeger  wrote:

> On 05/07/2016 06:09 PM, Ildikó Váncsa wrote:
> > Hi Matt,
> >
> > I'm open to discuss what would be the best way forward in this topic.
> First of all I would like to understand the intention with document
> structures long term to see how we can have a scalable and maintainable
> process.
> >
> > My experience is that keeping the documentation up to date separately
> from the code can be difficult that results in outdated materials, which
> also leads to bad user experience and impression.
> >
> > Would this topic be sufficient for one of the team meetings?
>
> Right now we have the Install Guide as first guide where we move content
> to the teams and still want to provide this from one place.
>
> I suggest that we do the Install Guide first and then consider whether
> that is a model that we should use for other documents as well,
>

Another example model to keep an eye on is the current move of content from
api-site to project repos. Let's see how that goes as well --
quality/accuracy, usefulness, and ongoing maintenance as first goals.

Anne


>
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>HRB 21284 (AG Nürnberg)
> GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>
> ___
> OpenStack-docs mailing list
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



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

Re: [openstack-dev] [OpenStack-docs] What's Up, Doc? 6 May 2016

2016-05-07 Thread Ildikó Váncsa 


> -Original Message-
> From: Andreas Jaeger [mailto:a...@suse.com]
> Sent: May 07, 2016 20:51
> To: Ildikó Váncsa; 'Matt Kassawara'
> Cc: OpenStack Development Mailing List; enstack.org
> Subject: Re: [OpenStack-docs] What's Up, Doc? 6 May 2016
> 
> On 05/07/2016 06:09 PM, Ildikó Váncsa wrote:
> > Hi Matt,
> >
> > I'm open to discuss what would be the best way forward in this topic. First 
> > of all I would like to understand the intention with
> document structures long term to see how we can have a scalable and 
> maintainable process.
> >
> > My experience is that keeping the documentation up to date separately from 
> > the code can be difficult that results in outdated
> materials, which also leads to bad user experience and impression.
> >
> > Would this topic be sufficient for one of the team meetings?
> 
> Right now we have the Install Guide as first guide where we move content to 
> the teams and still want to provide this from one place.
> 
> I suggest that we do the Install Guide first and then consider whether that 
> is a model that we should use for other documents as well,

Ok, that sounds good. Thanks Andreas for clarifying.

Best Regards,
Ildikó

> 
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>HRB 21284 (AG Nürnberg)
> GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126

__
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] What's Up, Doc? 6 May 2016

2016-05-07 Thread Andreas Jaeger 
On 05/07/2016 06:09 PM, Ildikó Váncsa wrote:
> Hi Matt,
> 
> I'm open to discuss what would be the best way forward in this topic. First 
> of all I would like to understand the intention with document structures long 
> term to see how we can have a scalable and maintainable process.
> 
> My experience is that keeping the documentation up to date separately from 
> the code can be difficult that results in outdated materials, which also 
> leads to bad user experience and impression.
> 
> Would this topic be sufficient for one of the team meetings?

Right now we have the Install Guide as first guide where we move content
to the teams and still want to provide this from one place.

I suggest that we do the Install Guide first and then consider whether
that is a model that we should use for other documents as well,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
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] What's Up, Doc? 6 May 2016

2016-05-07 Thread Ildikó Váncsa 
Hi Matt,

I'm open to discuss what would be the best way forward in this topic. First of 
all I would like to understand the intention with document structures long term 
to see how we can have a scalable and maintainable process.

My experience is that keeping the documentation up to date separately from the 
code can be difficult that results in outdated materials, which also leads to 
bad user experience and impression.

Would this topic be sufficient for one of the team meetings?

Thanks and Best Regards,
Ildikó

> -Original Message-
> From: Matt Kassawara [mailto:mkassaw...@gmail.com]
> Sent: May 07, 2016 00:55
> To: Ildikó Váncsa
> Cc: Lana Brindley; enstack.org; OpenStack Development Mailing List; 
> openstack-i...@lists.openstack.org
> Subject: Re: [OpenStack-docs] What's Up, Doc? 6 May 2016
> 
> One significant advantage of central documentation involves providing content 
> in a single location with consistent structure or format
> that best serves the particular audience. Moving most or all documentation 
> into project trees essentially eliminates this advantage,
> leaving our audiences with an impression that OpenStack consists of many 
> loosely associated projects rather than a coherent cloud
> computing solution. However, as a contributor to a few other OpenStack 
> projects who helps other developers contribute to central
> documentation, I can understand some of the frustrations with it. I prefer to 
> resolve these frustrations and have some ideas that I
> intend to float in separate thread, but if you don't think that's possible, 
> consider submitting a spec to change the primary purpose of
> the central documentation team to simply managing links to content in the 
> project trees.
> 
> On Fri, May 6, 2016 at 10:03 AM, Ildikó Váncsa  
> wrote:
> 
> 
>   Hi Lana,
> 
>   Thanks for the summary, it's pretty good reading to catch up what 
> happened recently.
> 
>   I have one question, I might missed a few entries, so please point me 
> to the right document in this case. We had a
> docco session with the Telemetry team and we agreed on moving back the 
> documentation snippets, like for instance the Install
> Guide, to the project trees is a really good step and we're very supportive. 
> In this sense I would like to ask about the plans regarding
> the Admin guide. We have a chapter there, which is on one hand outdated and 
> on the other hand would be better to move under the
> project trees as well. Is this plan/desire in line with your plans regarding 
> that document?
> 
>   Thanks,
>   /Ildikó
> 
> 
>   > -Original Message-
>   > From: Lana Brindley [mailto:openst...@lanabrindley.com]
>   > Sent: May 06, 2016 08:13
>   > To: enstack.org; OpenStack Development Mailing List; 
> openstack-i...@lists.openstack.org
>   > Subject: What's Up, Doc? 6 May 2016
>   >
>   > Hi everyone,
>   >
>   > I hope you all had a safe journey home from Summit, and are now fully 
> recovered from all the excitement (and
> jetlag)! I'm really
>   > pleased with the amount of progress we made this time around. We have 
> a definitive set of goals for Newton, and I'm
> confident that
>   > they're all moving us towards a much better docs suite overall. Of 
> course, the biggest and most important work we
> have to do is to get
>   > our Install Guide changes underway. I'm very excited to see the new 
> method for documenting OpenStack installation,
> and can't wait
>   > to see all our big tent projects contributing to docs in such a 
> meaningful way. Thank you to everyone (in the room and
> online) who
>   > contributed to the Install Guide discussion, and helped us move 
> forward on this important project.
>   >
>   > In other news, I've written a wrapup of the Austin design summit on 
> my blog, which you might be interested in:
>   > 
> http://lanabrindley.com/2016/05/05/openstack-newton-summit-docs-wrapup/
>   >
>   > == Progress towards Newton ==
>   >
>   > 152 days to go!
>   >
>   > Bugs closed so far: 61
>   >
>   > Because we have such a specific set of deliverables carved out for 
> Newton, I've made them their own wiki page:
>   > https://wiki.openstack.org/wiki/Documentation/NewtonDeliverables
>   > Feel free to add more detail and cross things off as they are 
> achieved throughout the release. I will also do my best to
> ensure it's kept
>   > up to date for each newsletter.
>   >
>   > One of the first tasks we've started work on after Summit is moving 
> the Ops and HA Guides out of their own
> repositories and into
>   > openstack-manuals. As a result, those repositories are now frozen, 
> and any work you want to do on those books
> should be in
>   > openstack-manuals.
>   >
>   > We are almost ready to publish the new RST version of the Ops Guide, 
> there's just a few cleanup edits

Re: [openstack-dev] [OpenStack-docs] What's Up, Doc? 6 May 2016

2016-05-06 Thread Matt Kassawara 
One significant advantage of central documentation involves providing
content in a single location with consistent structure or format that best
serves the particular audience. Moving most or all documentation into
project trees essentially eliminates this advantage, leaving our audiences
with an impression that OpenStack consists of many loosely associated
projects rather than a coherent cloud computing solution. However, as a
contributor to a few other OpenStack projects who helps other developers
contribute to central documentation, I can understand some of the
frustrations with it. I prefer to resolve these frustrations and have some
ideas that I intend to float in separate thread, but if you don't think
that's possible, consider submitting a spec to change the primary purpose
of the central documentation team to simply managing links to content in
the project trees.

On Fri, May 6, 2016 at 10:03 AM, Ildikó Váncsa 
wrote:

> Hi Lana,
>
> Thanks for the summary, it's pretty good reading to catch up what happened
> recently.
>
> I have one question, I might missed a few entries, so please point me to
> the right document in this case. We had a docco session with the Telemetry
> team and we agreed on moving back the documentation snippets, like for
> instance the Install Guide, to the project trees is a really good step and
> we're very supportive. In this sense I would like to ask about the plans
> regarding the Admin guide. We have a chapter there, which is on one hand
> outdated and on the other hand would be better to move under the project
> trees as well. Is this plan/desire in line with your plans regarding that
> document?
>
> Thanks,
> /Ildikó
>
> > -Original Message-
> > From: Lana Brindley [mailto:openst...@lanabrindley.com]
> > Sent: May 06, 2016 08:13
> > To: enstack.org; OpenStack Development Mailing List;
> openstack-i...@lists.openstack.org
> > Subject: What's Up, Doc? 6 May 2016
> >
> > Hi everyone,
> >
> > I hope you all had a safe journey home from Summit, and are now fully
> recovered from all the excitement (and jetlag)! I'm really
> > pleased with the amount of progress we made this time around. We have a
> definitive set of goals for Newton, and I'm confident that
> > they're all moving us towards a much better docs suite overall. Of
> course, the biggest and most important work we have to do is to get
> > our Install Guide changes underway. I'm very excited to see the new
> method for documenting OpenStack installation, and can't wait
> > to see all our big tent projects contributing to docs in such a
> meaningful way. Thank you to everyone (in the room and online) who
> > contributed to the Install Guide discussion, and helped us move forward
> on this important project.
> >
> > In other news, I've written a wrapup of the Austin design summit on my
> blog, which you might be interested in:
> > http://lanabrindley.com/2016/05/05/openstack-newton-summit-docs-wrapup/
> >
> > == Progress towards Newton ==
> >
> > 152 days to go!
> >
> > Bugs closed so far: 61
> >
> > Because we have such a specific set of deliverables carved out for
> Newton, I've made them their own wiki page:
> > https://wiki.openstack.org/wiki/Documentation/NewtonDeliverables
> > Feel free to add more detail and cross things off as they are achieved
> throughout the release. I will also do my best to ensure it's kept
> > up to date for each newsletter.
> >
> > One of the first tasks we've started work on after Summit is moving the
> Ops and HA Guides out of their own repositories and into
> > openstack-manuals. As a result, those repositories are now frozen, and
> any work you want to do on those books should be in
> > openstack-manuals.
> >
> > We are almost ready to publish the new RST version of the Ops Guide,
> there's just a few cleanup edits going in now, so make sure you
> > have the right book, in the right repo from now on. This was our very
> last book remaining in DocBook XML, so the docs toolchain will
> > be removing DocBook XML support. See spec
> https://review.openstack.org/311698 for details.
> >
> > Another migration note is that the API reference content is moving from
> api-site to project specific repositories and api-site is now
> > frozen. For more detail, see Anne's email:
> http://lists.openstack.org/pipermail/openstack-docs/2016-May/008536.html
> >
> > == Mitaka wrapup ==
> >
> > We performed a Mitaka retrospective at Summit, notes are here:
> https://etherpad.openstack.org/p/austin-docs-mitakaretro
> >
> > In particular, I'd like to call out our hard working tools team Andreas
> and Christian, all our Speciality Team leads, and the Mitaka release
> > managers Brian and Olga. Well done on a very successful release,
> everyone :)
> >
> > Total bugs closed: 645
> >
> > == Site Stats ==
> >
> > Thanks to the lovely people at Foundation (thanks Allison!) I now have
> access to more stats than I could possibly guess what to do
> > with, and I'm hoping to be