Re: [openstack-dev] [nova][docs] Concerns with docs migration

[Sean Dague]

On 08/07/2017 05:04 PM, Clark Boylan wrote:
> On Wed, Aug 2, 2017, at 01:44 PM, Clark Boylan wrote:
>> On Wed, Aug 2, 2017, at 11:37 AM, Sean Dague wrote:
>>> On 08/02/2017 12:28 PM, Clark Boylan wrote:
 On Wed, Aug 2, 2017, at 07:55 AM, Matt Riedemann wrote:
> Now that Stephen Finucane is back from enjoying his youth and 
> gallivanting all over Europe, and we talked about a few things in IRC 
> this morning on the docs migration for Nova, I wanted to dump my 
> concerns here for broader consumption.
>
> 1. We know we have to fix a bunch of broken links by adding in redirects 
> [1] which sdague started here [2]. However, that apparently didn't catch 
> everything, e.g. [3], so I'm concerned we're missing other broken links. 
> Is there a way to find out?

 The infra team can generate lists of 404 urls fairly easily on the docs
 server. This won't show you everything but will show you what urls
 people are finding/using that 404.
>>>
>>> If we could get a weekly report of 404 urls posted somewhere public,
>>> that would be extremely useful, because the easy ones based on git
>>> renames are done, and everything else is going to require human
>>> inspection to figure out what the right landing target is.
>>>
>>
>> I've pushed https://review.openstack.org/#/c/490175/ which will generate
>> a report each day for roughly the last day's worth of 404s. You should
>> be able to see them at https://docs.openstack.org/404s once the change
>> merges and the cron job fires.
>>
>> You can see what that will look like (from my test runs) at
>> http://paste.openstack.org/show/617322/. Note that this isn't a complete
>> file because paste.openstack.org truncated it but you'll get the full
>> data from the wbeserver once this change merges.
> 
> http://files.openstack.org/docs-404s/ is now live (note it moved to
> http://files.openstack.org/docs-404s because that is where we are
> hosting raw bits of utility info for this hosting service). The current
> content there was just generated by running the scripts manually, but it
> should update daily at 0700UTC going forward.

Awesome. Thank you Clark.

-Sean

-- 
Sean Dague
http://dague.net

__
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] [nova][docs] Concerns with docs migration

[Doug Hellmann]

Excerpts from Clark Boylan's message of 2017-08-07 14:04:33 -0700:
> On Wed, Aug 2, 2017, at 01:44 PM, Clark Boylan wrote:
> > On Wed, Aug 2, 2017, at 11:37 AM, Sean Dague wrote:
> > > On 08/02/2017 12:28 PM, Clark Boylan wrote:
> > > > On Wed, Aug 2, 2017, at 07:55 AM, Matt Riedemann wrote:
> > > >> Now that Stephen Finucane is back from enjoying his youth and 
> > > >> gallivanting all over Europe, and we talked about a few things in IRC 
> > > >> this morning on the docs migration for Nova, I wanted to dump my 
> > > >> concerns here for broader consumption.
> > > >>
> > > >> 1. We know we have to fix a bunch of broken links by adding in 
> > > >> redirects 
> > > >> [1] which sdague started here [2]. However, that apparently didn't 
> > > >> catch 
> > > >> everything, e.g. [3], so I'm concerned we're missing other broken 
> > > >> links. 
> > > >> Is there a way to find out?
> > > > 
> > > > The infra team can generate lists of 404 urls fairly easily on the docs
> > > > server. This won't show you everything but will show you what urls
> > > > people are finding/using that 404.
> > > 
> > > If we could get a weekly report of 404 urls posted somewhere public,
> > > that would be extremely useful, because the easy ones based on git
> > > renames are done, and everything else is going to require human
> > > inspection to figure out what the right landing target is.
> > > 
> > 
> > I've pushed https://review.openstack.org/#/c/490175/ which will generate
> > a report each day for roughly the last day's worth of 404s. You should
> > be able to see them at https://docs.openstack.org/404s once the change
> > merges and the cron job fires.
> > 
> > You can see what that will look like (from my test runs) at
> > http://paste.openstack.org/show/617322/. Note that this isn't a complete
> > file because paste.openstack.org truncated it but you'll get the full
> > data from the wbeserver once this change merges.
> 
> http://files.openstack.org/docs-404s/ is now live (note it moved to
> http://files.openstack.org/docs-404s because that is where we are
> hosting raw bits of utility info for this hosting service). The current
> content there was just generated by running the scripts manually, but it
> should update daily at 0700UTC going forward.
> 
> Hope this helps,
> Clark
> 

Thanks Clark, that's going to be really useful.

Doug

__
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] [nova][docs] Concerns with docs migration

[Clark Boylan]

On Wed, Aug 2, 2017, at 01:44 PM, Clark Boylan wrote:
> On Wed, Aug 2, 2017, at 11:37 AM, Sean Dague wrote:
> > On 08/02/2017 12:28 PM, Clark Boylan wrote:
> > > On Wed, Aug 2, 2017, at 07:55 AM, Matt Riedemann wrote:
> > >> Now that Stephen Finucane is back from enjoying his youth and 
> > >> gallivanting all over Europe, and we talked about a few things in IRC 
> > >> this morning on the docs migration for Nova, I wanted to dump my 
> > >> concerns here for broader consumption.
> > >>
> > >> 1. We know we have to fix a bunch of broken links by adding in redirects 
> > >> [1] which sdague started here [2]. However, that apparently didn't catch 
> > >> everything, e.g. [3], so I'm concerned we're missing other broken links. 
> > >> Is there a way to find out?
> > > 
> > > The infra team can generate lists of 404 urls fairly easily on the docs
> > > server. This won't show you everything but will show you what urls
> > > people are finding/using that 404.
> > 
> > If we could get a weekly report of 404 urls posted somewhere public,
> > that would be extremely useful, because the easy ones based on git
> > renames are done, and everything else is going to require human
> > inspection to figure out what the right landing target is.
> > 
> 
> I've pushed https://review.openstack.org/#/c/490175/ which will generate
> a report each day for roughly the last day's worth of 404s. You should
> be able to see them at https://docs.openstack.org/404s once the change
> merges and the cron job fires.
> 
> You can see what that will look like (from my test runs) at
> http://paste.openstack.org/show/617322/. Note that this isn't a complete
> file because paste.openstack.org truncated it but you'll get the full
> data from the wbeserver once this change merges.

http://files.openstack.org/docs-404s/ is now live (note it moved to
http://files.openstack.org/docs-404s because that is where we are
hosting raw bits of utility info for this hosting service). The current
content there was just generated by running the scripts manually, but it
should update daily at 0700UTC going forward.

Hope this helps,
Clark

__
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] [nova][docs] Concerns with docs migration

[Ruby Loo]

On Wed, Aug 2, 2017 at 10:55 AM, Matt Riedemann  wrote:

> ...
>
> b) I think that if we're going to refactor the Nova devref home page to be
> a certain format, then we should really consider doing the same thing in
> the other projects, because today they are all different formats [5][6][7].
> This is likely a cross-project discussion for the Queens PTG to determine
> if the home page for the projects should look similar. It seems they should
> given the uniformity that the Foundation has been working toward lately.
> ...

[1] http://lists.openstack.org/pipermail/openstack-dev/2017-Augu
> st/120418.html
> [2] https://review.openstack.org/#/c/489650/
> [3] https://review.openstack.org/#/c/489641/
> [4] https://review.openstack.org/#/c/478485/
> [5] https://docs.openstack.org/cinder/latest/
> [6] https://docs.openstack.org/glance/latest/
> [7] https://docs.openstack.org/neutron/latest/
>
>
We had this discussion in ironic-land as well. I don't even consider it a
devref home page any more; it seems more like a landing page for 'all
things '. I may be opinionated sometimes ;), but if
some people could come to an agreement on how we could make these landing
pages consistent amongst most, if not all, of the openstack projects, I'll
follow :)

--ruby
__
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] [nova][docs] Concerns with docs migration

[Sean Dague]

On 08/02/2017 08:53 PM, Ghanshyam Mann wrote:
> On Thu, Aug 3, 2017 at 1:20 AM, Doug Hellmann  wrote:
>> Excerpts from Akihiro Motoki's message of 2017-08-03 01:02:59 +0900:
>>> 2017-08-03 0:52 GMT+09:00 Doug Hellmann :
 Excerpts from Stephen Finucane's message of 2017-08-02 16:35:23 +0100:
> On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:
>> On 08/02/2017 09:22 AM, Stephen Finucane wrote:
>>> On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
 3. The patch for the import of the admin guide [8] is missing some CLI
 specific pages which are pretty useful given they aren't documented
 anywhere else, like the forced_host part of the compute API [9].
 Basically anything that's cli-nova-* in the admin guide should be in 
 the
 Nova docs. It's also missing the compute-flavors page [10] which is
 pretty important for using OpenStack at all.
>>>
>>> This is a tricky one. Based on previous discussions with dhellmann, the
>>> plan
>>> seems to be to replace any references to 'nova xxx' or 'openstack xxx'
>>> commands
>>> (i.e. commands using python-novaclient or python-openstackclient) in 
>>> favour
>>> of
>>> 'curl'-based requests. The idea here is that the Python clients are not 
>>> the
>>> only clients available, and we shouldn't be "mandating" their use by
>>> referencing them in the docs. I get this, though I don't fully agree 
>>> with
>>> it
>>> (who really uses curl?)
>>
>> Are we going to document the python clients elsewhere then?
>
> I think the docs would go into the respective python clients docs?

 Right. I don't remember the details of the curl discussion, but I
 think what I was trying to say there was that the "nova" command
 line tool installed via python-novaclient should be documented as
 part of the openstack/python-novaclient repo rather than openstack/nova.
 A CLI reference for nova-manage, which I think is in openstack/nova,
 could be documented in openstack/nova.

 Basically, put the docs with the code, which is the whole point of this
 migration.
>>>
>>> It is true for CLI reference.
>>> The gray zone is CLI stuffs in the admin guide and/or end-user guide.
>>> I think this is the point Matt raised.
>>> cli-nova-* stuffs in the admin guide was per topic like launching instance,
>>> migrating instances and so on. It is actually beyond the CLI reference to 
>>> me.
>>> It is about how to use specific features of nova.
>>> IMHO this kind of stuffs can be covered by the admin guide or user guide,
>>> so it fits into openstack/nova (or other server projects).
>>
>> Yeah, I don't know.
>>
>> My gut response is to say that if the example uses nova-manage or
>> one of the nova service executables, then that makes sense to leave
>> in the nova tree, but otherwise it should go into either the
>> python-novaclient or python-openstackclient repositories (depending
>> on which command line tool is used in the example).
>>
>> On the other hand, I can see that being somewhat confusing for
>> someone who lands at the nova docs and can't find instructions for
>> how to use it. Maybe less confusing, though, than if I am not
>> *running* nova but am trying to use a nova deployed by someone else
>> and I start from the python-novaclient or python-openstackclient
>> docs because I installed one of those in order to talk to nova.
> 
> This is nice point. If nova going to have those doc(using cli), it
> could be confusing for new folks about using novaclient/osc commands.
> They might have installed python-novaclient and try to use "openstack
> server create" because Nova doc says. Or it can be other client over
> nova APIs.
> 
> Also there is chance that Nova might have some obsolete doc (till
> someone use those and report bug)  if any command changed (very rare)
> or some param going to remove with deprecated process.
> 
> IMO, Nova doc should talk about more conceptual or operation things
> and then give reference to CLI doc as example.
> For example:
> "Launch VM doc in Nova" tells about all precondition to launch VM and
> APIs (it can be API name or API ref or Curl example) to get required
> data and launch VM and at the end give reference to CLI (novaclient or
> osc) doc where set of CLI are shown for that operation. If no CLI doc
> exist for particular operation, then nova doc still holds good
> information of doing that using APIs.

This is about audience and usage. We have the following audience and users:

* CLI users (nova cli or openstack client)
* Horizon users
* API users (possibly using python APIs, possibly others)

When a person shows up at our site from where ever, we should assume
they are a CLI user. It's universal, and easy to show examples. It's
also just simpler to integrate these examples then it is to integrate
Horizon usage.

API users 

Re: [openstack-dev] [nova][docs] Concerns with docs migration

[Sean Dague]

On 08/02/2017 03:32 PM, Dean Troyer wrote:
> On Wed, Aug 2, 2017 at 11:20 AM, Doug Hellmann  wrote:
>> My gut response is to say that if the example uses nova-manage or
>> one of the nova service executables, then that makes sense to leave
>> in the nova tree, but otherwise it should go into either the
>> python-novaclient or python-openstackclient repositories (depending
>> on which command line tool is used in the example).
> 
> I don't think this is a good rule of thumb...
> 
>> On the other hand, I can see that being somewhat confusing for
>> someone who lands at the nova docs and can't find instructions for
>> how to use it. Maybe less confusing, though, than if I am not
>> *running* nova but am trying to use a nova deployed by someone else
>> and I start from the python-novaclient or python-openstackclient
>> docs because I installed one of those in order to talk to nova.
> 
> When the point of the example is to illustrate configuring nova, the
> example should stay with the nova code, even if it uses novaclient or
> osc.  The examples that are about _using_ novaclient or osc belong in
> those repos, but where they are just a means to configuring something
> in nova, they should remain with nova and use the tools that users are
> expected to be familiar with (novaclient and/or osc in this example).
> 
>> I thought "put the docs with the code" would be a simple enough
>> rule that we wouldn't have to think too hard about where to put
>> individual example files, which would speed up the migration.
> 
> If I find a doc that tells me how to set up a VM with a Neutron
> network and ports and subnets and floating IPs that uses curl, I'm not
> reading farther.

++ that is actually kind of a punch in the face to our users

-Sean

-- 
Sean Dague
http://dague.net

__
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] [nova][docs] Concerns with docs migration

[Ghanshyam Mann]

On Thu, Aug 3, 2017 at 1:20 AM, Doug Hellmann  wrote:
> Excerpts from Akihiro Motoki's message of 2017-08-03 01:02:59 +0900:
>> 2017-08-03 0:52 GMT+09:00 Doug Hellmann :
>> > Excerpts from Stephen Finucane's message of 2017-08-02 16:35:23 +0100:
>> >> On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:
>> >> > On 08/02/2017 09:22 AM, Stephen Finucane wrote:
>> >> > > On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
>> >> > > > 3. The patch for the import of the admin guide [8] is missing some 
>> >> > > > CLI
>> >> > > > specific pages which are pretty useful given they aren't documented
>> >> > > > anywhere else, like the forced_host part of the compute API [9].
>> >> > > > Basically anything that's cli-nova-* in the admin guide should be 
>> >> > > > in the
>> >> > > > Nova docs. It's also missing the compute-flavors page [10] which is
>> >> > > > pretty important for using OpenStack at all.
>> >> > >
>> >> > > This is a tricky one. Based on previous discussions with dhellmann, 
>> >> > > the
>> >> > > plan
>> >> > > seems to be to replace any references to 'nova xxx' or 'openstack xxx'
>> >> > > commands
>> >> > > (i.e. commands using python-novaclient or python-openstackclient) in 
>> >> > > favour
>> >> > > of
>> >> > > 'curl'-based requests. The idea here is that the Python clients are 
>> >> > > not the
>> >> > > only clients available, and we shouldn't be "mandating" their use by
>> >> > > referencing them in the docs. I get this, though I don't fully agree 
>> >> > > with
>> >> > > it
>> >> > > (who really uses curl?)
>> >> >
>> >> > Are we going to document the python clients elsewhere then?
>> >>
>> >> I think the docs would go into the respective python clients docs?
>> >
>> > Right. I don't remember the details of the curl discussion, but I
>> > think what I was trying to say there was that the "nova" command
>> > line tool installed via python-novaclient should be documented as
>> > part of the openstack/python-novaclient repo rather than openstack/nova.
>> > A CLI reference for nova-manage, which I think is in openstack/nova,
>> > could be documented in openstack/nova.
>> >
>> > Basically, put the docs with the code, which is the whole point of this
>> > migration.
>>
>> It is true for CLI reference.
>> The gray zone is CLI stuffs in the admin guide and/or end-user guide.
>> I think this is the point Matt raised.
>> cli-nova-* stuffs in the admin guide was per topic like launching instance,
>> migrating instances and so on. It is actually beyond the CLI reference to me.
>> It is about how to use specific features of nova.
>> IMHO this kind of stuffs can be covered by the admin guide or user guide,
>> so it fits into openstack/nova (or other server projects).
>
> Yeah, I don't know.
>
> My gut response is to say that if the example uses nova-manage or
> one of the nova service executables, then that makes sense to leave
> in the nova tree, but otherwise it should go into either the
> python-novaclient or python-openstackclient repositories (depending
> on which command line tool is used in the example).
>
> On the other hand, I can see that being somewhat confusing for
> someone who lands at the nova docs and can't find instructions for
> how to use it. Maybe less confusing, though, than if I am not
> *running* nova but am trying to use a nova deployed by someone else
> and I start from the python-novaclient or python-openstackclient
> docs because I installed one of those in order to talk to nova.

This is nice point. If nova going to have those doc(using cli), it
could be confusing for new folks about using novaclient/osc commands.
They might have installed python-novaclient and try to use "openstack
server create" because Nova doc says. Or it can be other client over
nova APIs.

Also there is chance that Nova might have some obsolete doc (till
someone use those and report bug)  if any command changed (very rare)
or some param going to remove with deprecated process.

IMO, Nova doc should talk about more conceptual or operation things
and then give reference to CLI doc as example.
For example:
"Launch VM doc in Nova" tells about all precondition to launch VM and
APIs (it can be API name or API ref or Curl example) to get required
data and launch VM and at the end give reference to CLI (novaclient or
osc) doc where set of CLI are shown for that operation. If no CLI doc
exist for particular operation, then nova doc still holds good
information of doing that using APIs.


>
> I thought "put the docs with the code" would be a simple enough
> rule that we wouldn't have to think too hard about where to put
> individual example files, which would speed up the migration.
>
> Doug
>
>>
>> Akihiro
>>
>> >
>> > Doug
>> >

..1 
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-guide/source/cli-launch-instances.rst

-gmann


>> > __
>> > OpenStack 

Re: [openstack-dev] [nova][docs] Concerns with docs migration

[Doug Hellmann]

Excerpts from Clark Boylan's message of 2017-08-02 13:44:26 -0700:
> On Wed, Aug 2, 2017, at 11:37 AM, Sean Dague wrote:
> > On 08/02/2017 12:28 PM, Clark Boylan wrote:
> > > On Wed, Aug 2, 2017, at 07:55 AM, Matt Riedemann wrote:
> > >> Now that Stephen Finucane is back from enjoying his youth and 
> > >> gallivanting all over Europe, and we talked about a few things in IRC 
> > >> this morning on the docs migration for Nova, I wanted to dump my 
> > >> concerns here for broader consumption.
> > >>
> > >> 1. We know we have to fix a bunch of broken links by adding in redirects 
> > >> [1] which sdague started here [2]. However, that apparently didn't catch 
> > >> everything, e.g. [3], so I'm concerned we're missing other broken links. 
> > >> Is there a way to find out?
> > > 
> > > The infra team can generate lists of 404 urls fairly easily on the docs
> > > server. This won't show you everything but will show you what urls
> > > people are finding/using that 404.
> > 
> > If we could get a weekly report of 404 urls posted somewhere public,
> > that would be extremely useful, because the easy ones based on git
> > renames are done, and everything else is going to require human
> > inspection to figure out what the right landing target is.
> > 
> 
> I've pushed https://review.openstack.org/#/c/490175/ which will generate
> a report each day for roughly the last day's worth of 404s. You should
> be able to see them at https://docs.openstack.org/404s once the change
> merges and the cron job fires.
> 
> You can see what that will look like (from my test runs) at
> http://paste.openstack.org/show/617322/. Note that this isn't a complete
> file because paste.openstack.org truncated it but you'll get the full
> data from the wbeserver once this change merges.
> 
> Clark
> 

Wonderful, thank you, Clark!

Doug

__
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] [nova][docs] Concerns with docs migration

[Doug Hellmann]

Excerpts from Sean Dague's message of 2017-08-02 14:34:40 -0400:
> On 08/02/2017 12:20 PM, Doug Hellmann wrote:
> > Excerpts from Akihiro Motoki's message of 2017-08-03 01:02:59 +0900:
> >> 2017-08-03 0:52 GMT+09:00 Doug Hellmann :
> >>> Excerpts from Stephen Finucane's message of 2017-08-02 16:35:23 +0100:
>  On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:
> > On 08/02/2017 09:22 AM, Stephen Finucane wrote:
> >> On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
> >>> 3. The patch for the import of the admin guide [8] is missing some CLI
> >>> specific pages which are pretty useful given they aren't documented
> >>> anywhere else, like the forced_host part of the compute API [9].
> >>> Basically anything that's cli-nova-* in the admin guide should be in 
> >>> the
> >>> Nova docs. It's also missing the compute-flavors page [10] which is
> >>> pretty important for using OpenStack at all.
> >>
> >> This is a tricky one. Based on previous discussions with dhellmann, the
> >> plan
> >> seems to be to replace any references to 'nova xxx' or 'openstack xxx'
> >> commands
> >> (i.e. commands using python-novaclient or python-openstackclient) in 
> >> favour
> >> of
> >> 'curl'-based requests. The idea here is that the Python clients are 
> >> not the
> >> only clients available, and we shouldn't be "mandating" their use by
> >> referencing them in the docs. I get this, though I don't fully agree 
> >> with
> >> it
> >> (who really uses curl?)
> >
> > Are we going to document the python clients elsewhere then?
> 
>  I think the docs would go into the respective python clients docs?
> >>>
> >>> Right. I don't remember the details of the curl discussion, but I
> >>> think what I was trying to say there was that the "nova" command
> >>> line tool installed via python-novaclient should be documented as
> >>> part of the openstack/python-novaclient repo rather than openstack/nova.
> >>> A CLI reference for nova-manage, which I think is in openstack/nova,
> >>> could be documented in openstack/nova.
> >>>
> >>> Basically, put the docs with the code, which is the whole point of this
> >>> migration.
> >>
> >> It is true for CLI reference.
> >> The gray zone is CLI stuffs in the admin guide and/or end-user guide.
> >> I think this is the point Matt raised.
> >> cli-nova-* stuffs in the admin guide was per topic like launching instance,
> >> migrating instances and so on. It is actually beyond the CLI reference to 
> >> me.
> >> It is about how to use specific features of nova.
> >> IMHO this kind of stuffs can be covered by the admin guide or user guide,
> >> so it fits into openstack/nova (or other server projects).
> > 
> > Yeah, I don't know.
> > 
> > My gut response is to say that if the example uses nova-manage or
> > one of the nova service executables, then that makes sense to leave
> > in the nova tree, but otherwise it should go into either the
> > python-novaclient or python-openstackclient repositories (depending
> > on which command line tool is used in the example).
> > 
> > On the other hand, I can see that being somewhat confusing for
> > someone who lands at the nova docs and can't find instructions for
> > how to use it. Maybe less confusing, though, than if I am not
> > *running* nova but am trying to use a nova deployed by someone else
> > and I start from the python-novaclient or python-openstackclient
> > docs because I installed one of those in order to talk to nova.
> > 
> > I thought "put the docs with the code" would be a simple enough
> > rule that we wouldn't have to think too hard about where to put
> > individual example files, which would speed up the migration.
> 
> It's not so simple because years ago we decided nova-manage was mostly a
> bad thing (as you needed to run it on the API node and be able to read
> db creds with it), and exposed as much as possible of the administrative
> interfaces over the API. The policy of openstack client was that
> administrative commands would not go in openstack client. So a bunch of
> what was once nova-manage (5 years ago), is part of the nova cli now,
> and not really implemented by other toolkits.
> 
> This is also why the python nova client is not going away any time soon.
> 
> -Sean
> 

That's fine. I still think that if the instructions are "how to use
the nova client to do X" then they should go in the nova client
repository, because they are really about how to use *that tool*
to do the task.  If they are written from the perspective of "how
to do X with the nova API", that's a different case and it makes
sense to put them in the nova repository.

Ultimately, though, it's up to the nova team to decide where they want
to put the docs.

Doug

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 

Re: [openstack-dev] [nova][docs] Concerns with docs migration

[Clark Boylan]

On Wed, Aug 2, 2017, at 11:37 AM, Sean Dague wrote:
> On 08/02/2017 12:28 PM, Clark Boylan wrote:
> > On Wed, Aug 2, 2017, at 07:55 AM, Matt Riedemann wrote:
> >> Now that Stephen Finucane is back from enjoying his youth and 
> >> gallivanting all over Europe, and we talked about a few things in IRC 
> >> this morning on the docs migration for Nova, I wanted to dump my 
> >> concerns here for broader consumption.
> >>
> >> 1. We know we have to fix a bunch of broken links by adding in redirects 
> >> [1] which sdague started here [2]. However, that apparently didn't catch 
> >> everything, e.g. [3], so I'm concerned we're missing other broken links. 
> >> Is there a way to find out?
> > 
> > The infra team can generate lists of 404 urls fairly easily on the docs
> > server. This won't show you everything but will show you what urls
> > people are finding/using that 404.
> 
> If we could get a weekly report of 404 urls posted somewhere public,
> that would be extremely useful, because the easy ones based on git
> renames are done, and everything else is going to require human
> inspection to figure out what the right landing target is.
> 

I've pushed https://review.openstack.org/#/c/490175/ which will generate
a report each day for roughly the last day's worth of 404s. You should
be able to see them at https://docs.openstack.org/404s once the change
merges and the cron job fires.

You can see what that will look like (from my test runs) at
http://paste.openstack.org/show/617322/. Note that this isn't a complete
file because paste.openstack.org truncated it but you'll get the full
data from the wbeserver once this change merges.

Clark

__
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] [nova][docs] Concerns with docs migration

[Dean Troyer]

On Wed, Aug 2, 2017 at 11:20 AM, Doug Hellmann  wrote:
> My gut response is to say that if the example uses nova-manage or
> one of the nova service executables, then that makes sense to leave
> in the nova tree, but otherwise it should go into either the
> python-novaclient or python-openstackclient repositories (depending
> on which command line tool is used in the example).

I don't think this is a good rule of thumb...

> On the other hand, I can see that being somewhat confusing for
> someone who lands at the nova docs and can't find instructions for
> how to use it. Maybe less confusing, though, than if I am not
> *running* nova but am trying to use a nova deployed by someone else
> and I start from the python-novaclient or python-openstackclient
> docs because I installed one of those in order to talk to nova.

When the point of the example is to illustrate configuring nova, the
example should stay with the nova code, even if it uses novaclient or
osc.  The examples that are about _using_ novaclient or osc belong in
those repos, but where they are just a means to configuring something
in nova, they should remain with nova and use the tools that users are
expected to be familiar with (novaclient and/or osc in this example).

> I thought "put the docs with the code" would be a simple enough
> rule that we wouldn't have to think too hard about where to put
> individual example files, which would speed up the migration.

If I find a doc that tells me how to set up a VM with a Neutron
network and ports and subnets and floating IPs that uses curl, I'm not
reading farther.

dt

-- 

Dean Troyer
dtro...@gmail.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] [nova][docs] Concerns with docs migration

[Anne Gentle | Just Write Click]

> On Aug 2, 2017, at 1:37 PM, Sean Dague  wrote:
> 
>> On 08/02/2017 12:28 PM, Clark Boylan wrote:
>>> On Wed, Aug 2, 2017, at 07:55 AM, Matt Riedemann wrote:
>>> Now that Stephen Finucane is back from enjoying his youth and 
>>> gallivanting all over Europe, and we talked about a few things in IRC 
>>> this morning on the docs migration for Nova, I wanted to dump my 
>>> concerns here for broader consumption.
>>> 
>>> 1. We know we have to fix a bunch of broken links by adding in redirects 
>>> [1] which sdague started here [2]. However, that apparently didn't catch 
>>> everything, e.g. [3], so I'm concerned we're missing other broken links. 
>>> Is there a way to find out?
>> 
>> The infra team can generate lists of 404 urls fairly easily on the docs
>> server. This won't show you everything but will show you what urls
>> people are finding/using that 404.
> 
> If we could get a weekly report of 404 urls posted somewhere public,
> that would be extremely useful, because the easy ones based on git
> renames are done, and everything else is going to require human
> inspection to figure out what the right landing target is.
> 

Fantastic idea. 

I love how many more ideas we are getting as more brains share them.

>-Sean
> 
> -- 
> Sean Dague
> http://dague.net
> 
> __
> 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] [nova][docs] Concerns with docs migration

[Sean Dague]

On 08/02/2017 12:28 PM, Clark Boylan wrote:
> On Wed, Aug 2, 2017, at 07:55 AM, Matt Riedemann wrote:
>> Now that Stephen Finucane is back from enjoying his youth and 
>> gallivanting all over Europe, and we talked about a few things in IRC 
>> this morning on the docs migration for Nova, I wanted to dump my 
>> concerns here for broader consumption.
>>
>> 1. We know we have to fix a bunch of broken links by adding in redirects 
>> [1] which sdague started here [2]. However, that apparently didn't catch 
>> everything, e.g. [3], so I'm concerned we're missing other broken links. 
>> Is there a way to find out?
> 
> The infra team can generate lists of 404 urls fairly easily on the docs
> server. This won't show you everything but will show you what urls
> people are finding/using that 404.

If we could get a weekly report of 404 urls posted somewhere public,
that would be extremely useful, because the easy ones based on git
renames are done, and everything else is going to require human
inspection to figure out what the right landing target is.

-Sean

-- 
Sean Dague
http://dague.net

__
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] [nova][docs] Concerns with docs migration

[Sean Dague]

On 08/02/2017 12:20 PM, Doug Hellmann wrote:
> Excerpts from Akihiro Motoki's message of 2017-08-03 01:02:59 +0900:
>> 2017-08-03 0:52 GMT+09:00 Doug Hellmann :
>>> Excerpts from Stephen Finucane's message of 2017-08-02 16:35:23 +0100:
 On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:
> On 08/02/2017 09:22 AM, Stephen Finucane wrote:
>> On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
>>> 3. The patch for the import of the admin guide [8] is missing some CLI
>>> specific pages which are pretty useful given they aren't documented
>>> anywhere else, like the forced_host part of the compute API [9].
>>> Basically anything that's cli-nova-* in the admin guide should be in the
>>> Nova docs. It's also missing the compute-flavors page [10] which is
>>> pretty important for using OpenStack at all.
>>
>> This is a tricky one. Based on previous discussions with dhellmann, the
>> plan
>> seems to be to replace any references to 'nova xxx' or 'openstack xxx'
>> commands
>> (i.e. commands using python-novaclient or python-openstackclient) in 
>> favour
>> of
>> 'curl'-based requests. The idea here is that the Python clients are not 
>> the
>> only clients available, and we shouldn't be "mandating" their use by
>> referencing them in the docs. I get this, though I don't fully agree with
>> it
>> (who really uses curl?)
>
> Are we going to document the python clients elsewhere then?

 I think the docs would go into the respective python clients docs?
>>>
>>> Right. I don't remember the details of the curl discussion, but I
>>> think what I was trying to say there was that the "nova" command
>>> line tool installed via python-novaclient should be documented as
>>> part of the openstack/python-novaclient repo rather than openstack/nova.
>>> A CLI reference for nova-manage, which I think is in openstack/nova,
>>> could be documented in openstack/nova.
>>>
>>> Basically, put the docs with the code, which is the whole point of this
>>> migration.
>>
>> It is true for CLI reference.
>> The gray zone is CLI stuffs in the admin guide and/or end-user guide.
>> I think this is the point Matt raised.
>> cli-nova-* stuffs in the admin guide was per topic like launching instance,
>> migrating instances and so on. It is actually beyond the CLI reference to me.
>> It is about how to use specific features of nova.
>> IMHO this kind of stuffs can be covered by the admin guide or user guide,
>> so it fits into openstack/nova (or other server projects).
> 
> Yeah, I don't know.
> 
> My gut response is to say that if the example uses nova-manage or
> one of the nova service executables, then that makes sense to leave
> in the nova tree, but otherwise it should go into either the
> python-novaclient or python-openstackclient repositories (depending
> on which command line tool is used in the example).
> 
> On the other hand, I can see that being somewhat confusing for
> someone who lands at the nova docs and can't find instructions for
> how to use it. Maybe less confusing, though, than if I am not
> *running* nova but am trying to use a nova deployed by someone else
> and I start from the python-novaclient or python-openstackclient
> docs because I installed one of those in order to talk to nova.
> 
> I thought "put the docs with the code" would be a simple enough
> rule that we wouldn't have to think too hard about where to put
> individual example files, which would speed up the migration.

It's not so simple because years ago we decided nova-manage was mostly a
bad thing (as you needed to run it on the API node and be able to read
db creds with it), and exposed as much as possible of the administrative
interfaces over the API. The policy of openstack client was that
administrative commands would not go in openstack client. So a bunch of
what was once nova-manage (5 years ago), is part of the nova cli now,
and not really implemented by other toolkits.

This is also why the python nova client is not going away any time soon.

-Sean

-- 
Sean Dague
http://dague.net

__
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] [nova][docs] Concerns with docs migration

[Mathieu Gagné]

On Wed, Aug 2, 2017 at 12:28 PM, Clark Boylan  wrote:
> On Wed, Aug 2, 2017, at 07:55 AM, Matt Riedemann wrote:
>> Now that Stephen Finucane is back from enjoying his youth and
>> gallivanting all over Europe, and we talked about a few things in IRC
>> this morning on the docs migration for Nova, I wanted to dump my
>> concerns here for broader consumption.
>>
>> 1. We know we have to fix a bunch of broken links by adding in redirects
>> [1] which sdague started here [2]. However, that apparently didn't catch
>> everything, e.g. [3], so I'm concerned we're missing other broken links.
>> Is there a way to find out?
>
> The infra team can generate lists of 404 urls fairly easily on the docs
> server. This won't show you everything but will show you what urls
> people are finding/using that 404.
>

Thanks for proposing this proactive solution.
I find it *very frustrating* to Google something and land on a 404 error.
Especially when the user survey keeps asking "How often do users refer
to documentation from docs.openstack.org?"
I don't often refer to the documentation but as of today, when I does,
it's only to find the page I'm looking for has moved somewhere.
What kind of experience are we giving to the users and operators? (I'm
sure it's with good intents and for the best)

I'm glad people are addressing the redirection issues.

--
Mathieu

__
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] [nova][docs] Concerns with docs migration

[Stephen Finucane]

On Wed, 2017-08-02 at 09:28 -0700, Clark Boylan wrote:
> On Wed, Aug 2, 2017, at 07:55 AM, Matt Riedemann wrote:
> > Now that Stephen Finucane is back from enjoying his youth and 
> > gallivanting all over Europe, and we talked about a few things in IRC 
> > this morning on the docs migration for Nova, I wanted to dump my 
> > concerns here for broader consumption.
> > 
> > 1. We know we have to fix a bunch of broken links by adding in redirects 
> > [1] which sdague started here [2]. However, that apparently didn't catch 
> > everything, e.g. [3], so I'm concerned we're missing other broken links. 
> > Is there a way to find out?
> 
> The infra team can generate lists of 404 urls fairly easily on the docs
> server. This won't show you everything but will show you what urls
> people are finding/using that 404.

I'd appreciate that. Have been going through things manually this afternoon but
it's slow work. Can you do this (or know who could)?

Stephen

__
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] [nova][docs] Concerns with docs migration

[Clark Boylan]

On Wed, Aug 2, 2017, at 07:55 AM, Matt Riedemann wrote:
> Now that Stephen Finucane is back from enjoying his youth and 
> gallivanting all over Europe, and we talked about a few things in IRC 
> this morning on the docs migration for Nova, I wanted to dump my 
> concerns here for broader consumption.
> 
> 1. We know we have to fix a bunch of broken links by adding in redirects 
> [1] which sdague started here [2]. However, that apparently didn't catch 
> everything, e.g. [3], so I'm concerned we're missing other broken links. 
> Is there a way to find out?

The infra team can generate lists of 404 urls fairly easily on the docs
server. This won't show you everything but will show you what urls
people are finding/using that 404.

> 

snip

> [1] 
> http://lists.openstack.org/pipermail/openstack-dev/2017-August/120418.html
> [2] https://review.openstack.org/#/c/489650/
> [3] https://review.openstack.org/#/c/489641/

Clark

__
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] [nova][docs] Concerns with docs migration

[Doug Hellmann]

Excerpts from Akihiro Motoki's message of 2017-08-03 01:02:59 +0900:
> 2017-08-03 0:52 GMT+09:00 Doug Hellmann :
> > Excerpts from Stephen Finucane's message of 2017-08-02 16:35:23 +0100:
> >> On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:
> >> > On 08/02/2017 09:22 AM, Stephen Finucane wrote:
> >> > > On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
> >> > > > 3. The patch for the import of the admin guide [8] is missing some 
> >> > > > CLI
> >> > > > specific pages which are pretty useful given they aren't documented
> >> > > > anywhere else, like the forced_host part of the compute API [9].
> >> > > > Basically anything that's cli-nova-* in the admin guide should be in 
> >> > > > the
> >> > > > Nova docs. It's also missing the compute-flavors page [10] which is
> >> > > > pretty important for using OpenStack at all.
> >> > >
> >> > > This is a tricky one. Based on previous discussions with dhellmann, the
> >> > > plan
> >> > > seems to be to replace any references to 'nova xxx' or 'openstack xxx'
> >> > > commands
> >> > > (i.e. commands using python-novaclient or python-openstackclient) in 
> >> > > favour
> >> > > of
> >> > > 'curl'-based requests. The idea here is that the Python clients are 
> >> > > not the
> >> > > only clients available, and we shouldn't be "mandating" their use by
> >> > > referencing them in the docs. I get this, though I don't fully agree 
> >> > > with
> >> > > it
> >> > > (who really uses curl?)
> >> >
> >> > Are we going to document the python clients elsewhere then?
> >>
> >> I think the docs would go into the respective python clients docs?
> >
> > Right. I don't remember the details of the curl discussion, but I
> > think what I was trying to say there was that the "nova" command
> > line tool installed via python-novaclient should be documented as
> > part of the openstack/python-novaclient repo rather than openstack/nova.
> > A CLI reference for nova-manage, which I think is in openstack/nova,
> > could be documented in openstack/nova.
> >
> > Basically, put the docs with the code, which is the whole point of this
> > migration.
> 
> It is true for CLI reference.
> The gray zone is CLI stuffs in the admin guide and/or end-user guide.
> I think this is the point Matt raised.
> cli-nova-* stuffs in the admin guide was per topic like launching instance,
> migrating instances and so on. It is actually beyond the CLI reference to me.
> It is about how to use specific features of nova.
> IMHO this kind of stuffs can be covered by the admin guide or user guide,
> so it fits into openstack/nova (or other server projects).

Yeah, I don't know.

My gut response is to say that if the example uses nova-manage or
one of the nova service executables, then that makes sense to leave
in the nova tree, but otherwise it should go into either the
python-novaclient or python-openstackclient repositories (depending
on which command line tool is used in the example).

On the other hand, I can see that being somewhat confusing for
someone who lands at the nova docs and can't find instructions for
how to use it. Maybe less confusing, though, than if I am not
*running* nova but am trying to use a nova deployed by someone else
and I start from the python-novaclient or python-openstackclient
docs because I installed one of those in order to talk to nova.

I thought "put the docs with the code" would be a simple enough
rule that we wouldn't have to think too hard about where to put
individual example files, which would speed up the migration.

Doug

> 
> Akihiro
> 
> >
> > Doug
> >
> > __
> > 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] [nova][docs] Concerns with docs migration

[Akihiro Motoki]

2017-08-03 0:52 GMT+09:00 Doug Hellmann :
> Excerpts from Stephen Finucane's message of 2017-08-02 16:35:23 +0100:
>> On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:
>> > On 08/02/2017 09:22 AM, Stephen Finucane wrote:
>> > > On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
>> > > > 3. The patch for the import of the admin guide [8] is missing some CLI
>> > > > specific pages which are pretty useful given they aren't documented
>> > > > anywhere else, like the forced_host part of the compute API [9].
>> > > > Basically anything that's cli-nova-* in the admin guide should be in 
>> > > > the
>> > > > Nova docs. It's also missing the compute-flavors page [10] which is
>> > > > pretty important for using OpenStack at all.
>> > >
>> > > This is a tricky one. Based on previous discussions with dhellmann, the
>> > > plan
>> > > seems to be to replace any references to 'nova xxx' or 'openstack xxx'
>> > > commands
>> > > (i.e. commands using python-novaclient or python-openstackclient) in 
>> > > favour
>> > > of
>> > > 'curl'-based requests. The idea here is that the Python clients are not 
>> > > the
>> > > only clients available, and we shouldn't be "mandating" their use by
>> > > referencing them in the docs. I get this, though I don't fully agree with
>> > > it
>> > > (who really uses curl?)
>> >
>> > Are we going to document the python clients elsewhere then?
>>
>> I think the docs would go into the respective python clients docs?
>
> Right. I don't remember the details of the curl discussion, but I
> think what I was trying to say there was that the "nova" command
> line tool installed via python-novaclient should be documented as
> part of the openstack/python-novaclient repo rather than openstack/nova.
> A CLI reference for nova-manage, which I think is in openstack/nova,
> could be documented in openstack/nova.
>
> Basically, put the docs with the code, which is the whole point of this
> migration.

It is true for CLI reference.
The gray zone is CLI stuffs in the admin guide and/or end-user guide.
I think this is the point Matt raised.
cli-nova-* stuffs in the admin guide was per topic like launching instance,
migrating instances and so on. It is actually beyond the CLI reference to me.
It is about how to use specific features of nova.
IMHO this kind of stuffs can be covered by the admin guide or user guide,
so it fits into openstack/nova (or other server projects).

Akihiro

>
> Doug
>
> __
> 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] [nova][docs] Concerns with docs migration

[Akihiro Motoki]

Thanks for summarizing the concerns. It is really helpful for all projects!

2017-08-02 23:55 GMT+09:00 Matt Riedemann :
> Now that Stephen Finucane is back from enjoying his youth and gallivanting
> all over Europe, and we talked about a few things in IRC this morning on the
> docs migration for Nova, I wanted to dump my concerns here for broader
> consumption.
>
> 1. We know we have to fix a bunch of broken links by adding in redirects [1]
> which sdague started here [2]. However, that apparently didn't catch
> everything, e.g. [3], so I'm concerned we're missing other broken links. Is
> there a way to find out?
>
> 2. The bottom change in the docs migration series for Nova is a massive
> refactor of the layout of the Nova devref [4]. That's something I don't want
> to do in Pike for two reasons:
>
> a) It's a huge change and we simply don't have the time to invest in
> properly assessing and reviewing it before Pike RC1.
>
> b) I think that if we're going to refactor the Nova devref home page to be a
> certain format, then we should really consider doing the same thing in the
> other projects, because today they are all different formats [5][6][7]. This
> is likely a cross-project discussion for the Queens PTG to determine if the
> home page for the projects should look similar. It seems they should given
> the uniformity that the Foundation has been working toward lately.

Totally agree for PTG topics. we need some guideline on what the top pages of
individual projects should be and what are expected for top pages of
sub directories.
When the doc-migration started, I chatted on this a bit with asettle.
The top page of each subdirectory (like admin, install and so on) are
expected to link
from a landing page on docs.openstack.org. On the other hand, we also need to
take care of the top page of individual projects. In neutron case, we
basically try to
accommodate all documents in the standard directory structure and keep
the top page as much as simple.
It is really nice to have a consistent guideline on this.

> 3. The patch for the import of the admin guide [8] is missing some CLI
> specific pages which are pretty useful given they aren't documented anywhere
> else, like the forced_host part of the compute API [9]. Basically anything
> that's cli-nova-* in the admin guide should be in the Nova docs. It's also
> missing the compute-flavors page [10] which is pretty important for using
> OpenStack at all.

Perhaps what we need are pages which explains how to use and configure
a specific feature using on CLI and/or some. It might be beyond the
scope of cli-nova-*.
I think the end-user and admin guides can be refactored per topic.

> 4. Similar to #3, but we don't have a patch yet for importing the user guide
> and there are several docs in the user guide that are Nova specific so I'd
> like to make sure we include those, like [11][12].
>
> [1]
> http://lists.openstack.org/pipermail/openstack-dev/2017-August/120418.html
> [2] https://review.openstack.org/#/c/489650/
> [3] https://review.openstack.org/#/c/489641/
> [4] https://review.openstack.org/#/c/478485/
> [5] https://docs.openstack.org/cinder/latest/
> [6] https://docs.openstack.org/glance/latest/
> [7] https://docs.openstack.org/neutron/latest/
> [8] https://review.openstack.org/#/c/477497/
> [9]
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-guide/source/cli-nova-specify-host.rst
> [10]
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-guide/source/compute-flavors.rst
> [11]
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-guide/source/cli-launch-instances.rst
> [12]
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-guide/source/cli-delete-an-instance.rst
>
> --
>
> Thanks,
>
> Matt
>
> __
> 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] [nova][docs] Concerns with docs migration

[Doug Hellmann]

Excerpts from Stephen Finucane's message of 2017-08-02 16:35:23 +0100:
> On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:
> > On 08/02/2017 09:22 AM, Stephen Finucane wrote:
> > > On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
> > > > 3. The patch for the import of the admin guide [8] is missing some CLI
> > > > specific pages which are pretty useful given they aren't documented
> > > > anywhere else, like the forced_host part of the compute API [9].
> > > > Basically anything that's cli-nova-* in the admin guide should be in the
> > > > Nova docs. It's also missing the compute-flavors page [10] which is
> > > > pretty important for using OpenStack at all.
> > > 
> > > This is a tricky one. Based on previous discussions with dhellmann, the
> > > plan
> > > seems to be to replace any references to 'nova xxx' or 'openstack xxx'
> > > commands
> > > (i.e. commands using python-novaclient or python-openstackclient) in 
> > > favour
> > > of
> > > 'curl'-based requests. The idea here is that the Python clients are not 
> > > the
> > > only clients available, and we shouldn't be "mandating" their use by
> > > referencing them in the docs. I get this, though I don't fully agree with
> > > it
> > > (who really uses curl?)
> >
> > Are we going to document the python clients elsewhere then?
> 
> I think the docs would go into the respective python clients docs?

Right. I don't remember the details of the curl discussion, but I
think what I was trying to say there was that the "nova" command
line tool installed via python-novaclient should be documented as
part of the openstack/python-novaclient repo rather than openstack/nova.
A CLI reference for nova-manage, which I think is in openstack/nova,
could be documented in openstack/nova.

Basically, put the docs with the code, which is the whole point of this
migration.

Doug

__
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] [nova][docs] Concerns with docs migration

[Stephen Finucane]

On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:
> On 08/02/2017 09:22 AM, Stephen Finucane wrote:
> > On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
> > > 3. The patch for the import of the admin guide [8] is missing some CLI
> > > specific pages which are pretty useful given they aren't documented
> > > anywhere else, like the forced_host part of the compute API [9].
> > > Basically anything that's cli-nova-* in the admin guide should be in the
> > > Nova docs. It's also missing the compute-flavors page [10] which is
> > > pretty important for using OpenStack at all.
> > 
> > This is a tricky one. Based on previous discussions with dhellmann, the
> > plan
> > seems to be to replace any references to 'nova xxx' or 'openstack xxx'
> > commands
> > (i.e. commands using python-novaclient or python-openstackclient) in favour
> > of
> > 'curl'-based requests. The idea here is that the Python clients are not the
> > only clients available, and we shouldn't be "mandating" their use by
> > referencing them in the docs. I get this, though I don't fully agree with
> > it
> > (who really uses curl?)
>
> Are we going to document the python clients elsewhere then?

I think the docs would go into the respective python clients docs?

> Personally I find it highly useful to have complete examples of how to do
> things with python-novaclient or python-openstackclient.

I agree. Personally, I'd like to see something like Stripe's API docs [1],
maybe through a not-yet-existant 'sphinx-slate' extension [2], but that seems a
lot of work for very little gain and would need serious maintaining.

> Given that any users of the raw HTTP API are likely going to be developers, 
> while users of the CLI tools may not be, it seems more important to give
> good examples of using the CLI tools.  Any developer should be able to figure
> out the underlying HTTP (using the --debug option of the CLI tool if
> necessary).

I think the main idea is that the 'python-*client's are not the only game in
town and should not be treated as such. Who these other clients are is a
question I don't personally know the answer to, however.

In any case, this is surely a post-Pike issue, as noted above.

Stephen

[1] https://stripe.com/docs/api
[2] https://github.com/lord/slate

__
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] [nova][docs] Concerns with docs migration

[Chris Dent]

On Wed, 2 Aug 2017, Stephen Finucane wrote:

Unfortunately I can't think of any cleverer way to identify these broken links
than manual inspection. I'll do this again for all the patches I've authored
and try to do them for any others I encounter.


if there's access available to the web server logs:

Get access to the server logs, grep for 404 response codes, sort by
url, order by count. Anything that has a high number should be
compared with the .htaccess file that Sean created.


This is a tricky one. Based on previous discussions with dhellmann, the plan
seems to be to replace any references to 'nova xxx' or 'openstack xxx' commands
(i.e. commands using python-novaclient or python-openstackclient) in favour of
'curl'-based requests. The idea here is that the Python clients are not the
only clients available, and we shouldn't be "mandating" their use by
referencing them in the docs. I get this, though I don't fully agree with it
(who really uses curl?). In any case though, this would surely be a big rewrite
and, per your concerns in #2 above,  doesn't sound like something we should be
doing in Pike. I guess a basic import is the way to go for now. I'll take care
of this.


As much as I think using the raw HTTP is an important learning
tool, using curl in the docs will make the docs very hard to
comprehend.

--
Chris Dent  (⊙＿⊙') https://anticdent.org/
freenode: cdent tw: @anticdent__
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] [nova][docs] Concerns with docs migration

[Chris Friesen]

On 08/02/2017 09:22 AM, Stephen Finucane wrote:

On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:



3. The patch for the import of the admin guide [8] is missing some CLI
specific pages which are pretty useful given they aren't documented
anywhere else, like the forced_host part of the compute API [9].
Basically anything that's cli-nova-* in the admin guide should be in the
Nova docs. It's also missing the compute-flavors page [10] which is
pretty important for using OpenStack at all.


This is a tricky one. Based on previous discussions with dhellmann, the plan
seems to be to replace any references to 'nova xxx' or 'openstack xxx' commands
(i.e. commands using python-novaclient or python-openstackclient) in favour of
'curl'-based requests. The idea here is that the Python clients are not the
only clients available, and we shouldn't be "mandating" their use by
referencing them in the docs. I get this, though I don't fully agree with it
(who really uses curl?)


Are we going to document the python clients elsewhere then?  Personally I find 
it highly useful to have complete examples of how to do things with 
python-novaclient or python-openstackclient.


Given that any users of the raw HTTP API are likely going to be developers, 
while users of the CLI tools may not be, it seems more important to give good 
examples of using the CLI tools.  Any developer should be able to figure out the 
underlying HTTP (using the --debug option of the CLI tool if necessary).


Chris

__
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] [nova][docs] Concerns with docs migration

[Stephen Finucane]

On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
> Now that Stephen Finucane is back from enjoying his youth and 
> gallivanting all over Europe, and we talked about a few things in IRC 
> this morning on the docs migration for Nova, I wanted to dump my 
> concerns here for broader consumption.
> 
> 1. We know we have to fix a bunch of broken links by adding in redirects 
> [1] which sdague started here [2]. However, that apparently didn't catch 
> everything, e.g. [3], so I'm concerned we're missing other broken links. 
> Is there a way to find out?

We knew this was going to be an issue, but I wasn't aware of any way to fix
this. The solution looks good though - nice work.

Unfortunately I can't think of any cleverer way to identify these broken links
than manual inspection. I'll do this again for all the patches I've authored
and try to do them for any others I encounter.

> 2. The bottom change in the docs migration series for Nova is a massive 
> refactor of the layout of the Nova devref [4]. That's something I don't 
> want to do in Pike for two reasons:
> 
> a) It's a huge change and we simply don't have the time to invest in 
> properly assessing and reviewing it before Pike RC1.
> 
> b) I think that if we're going to refactor the Nova devref home page to 
> be a certain format, then we should really consider doing the same thing 
> in the other projects, because today they are all different formats 
> [5][6][7]. This is likely a cross-project discussion for the Queens PTG 
> to determine if the home page for the projects should look similar. It 
> seems they should given the uniformity that the Foundation has been 
> working toward lately.

This is fair. I've been working on this with asettle and I personally agree
with a lot of the changes/design decisions made there. However, I understand
the time constraints so we can surely split this out. I'll work with asettle on
this too.

> 3. The patch for the import of the admin guide [8] is missing some CLI 
> specific pages which are pretty useful given they aren't documented 
> anywhere else, like the forced_host part of the compute API [9]. 
> Basically anything that's cli-nova-* in the admin guide should be in the 
> Nova docs. It's also missing the compute-flavors page [10] which is 
> pretty important for using OpenStack at all.

This is a tricky one. Based on previous discussions with dhellmann, the plan
seems to be to replace any references to 'nova xxx' or 'openstack xxx' commands
(i.e. commands using python-novaclient or python-openstackclient) in favour of
'curl'-based requests. The idea here is that the Python clients are not the
only clients available, and we shouldn't be "mandating" their use by
referencing them in the docs. I get this, though I don't fully agree with it
(who really uses curl?). In any case though, this would surely be a big rewrite
and, per your concerns in #2 above,  doesn't sound like something we should be
doing in Pike. I guess a basic import is the way to go for now. I'll take care
of this.

> 4. Similar to #3, but we don't have a patch yet for importing the user 
> guide and there are several docs in the user guide that are Nova 
> specific so I'd like to make sure we include those, like [11][12].

As above.

Stephen

> [1] 
> http://lists.openstack.org/pipermail/openstack-dev/2017-August/120418.html
> [2] https://review.openstack.org/#/c/489650/
> [3] https://review.openstack.org/#/c/489641/
> [4] https://review.openstack.org/#/c/478485/
> [5] https://docs.openstack.org/cinder/latest/
> [6] https://docs.openstack.org/glance/latest/
> [7] https://docs.openstack.org/neutron/latest/
> [8] https://review.openstack.org/#/c/477497/
> [9] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-gu
> ide/source/cli-nova-specify-host.rst
> [10] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-gu
> ide/source/compute-flavors.rst
> [11] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-gui
> de/source/cli-launch-instances.rst
> [12] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-gui
> de/source/cli-delete-an-instance.rst
> 


__
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] [nova][docs] Concerns with docs migration

[Stephen Finucane]

On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
> Now that Stephen Finucane is back from enjoying his youth and 
> gallivanting all over Europe, and we talked about a few things in IRC 
> this morning on the docs migration for Nova, I wanted to dump my 
> concerns here for broader consumption.
> 
> 1. We know we have to fix a bunch of broken links by adding in redirects 
> [1] which sdague started here [2]. However, that apparently didn't catch 
> everything, e.g. [3], so I'm concerned we're missing other broken links. 
> Is there a way to find out?

Manual inspection is probably the easiest way to go. 

> 2. The bottom change in the docs migration series for Nova is a massive 
> refactor of the layout of the Nova devref [4]. That's something I don't 
> want to do in Pike for two reasons:
> 
> a) It's a huge change and we simply don't have the time to invest in 
> properly assessing and reviewing it before Pike RC1.
> 
> b) I think that if we're going to refactor the Nova devref home page to 
> be a certain format, then we should really consider doing the same thing 
> in the other projects, because today they are all different formats 
> [5][6][7]. This is likely a cross-project discussion for the Queens PTG 
> to determine if the home page for the projects should look similar. It 
> seems they should given the uniformity that the Foundation has been 
> working toward lately.
> 
> 3. The patch for the import of the admin guide [8] is missing some CLI 
> specific pages which are pretty useful given they aren't documented 
> anywhere else, like the forced_host part of the compute API [9]. 
> Basically anything that's cli-nova-* in the admin guide should be in the 
> Nova docs. It's also missing the compute-flavors page [10] which is 
> pretty important for using OpenStack at all.
> 
> 4. Similar to #3, but we don't have a patch yet for importing the user 
> guide and there are several docs in the user guide that are Nova 
> specific so I'd like to make sure we include those, like [11][12].
> 
> [1] 
> http://lists.openstack.org/pipermail/openstack-dev/2017-August/120418.html
> [2] https://review.openstack.org/#/c/489650/
> [3] https://review.openstack.org/#/c/489641/
> [4] https://review.openstack.org/#/c/478485/
> [5] https://docs.openstack.org/cinder/latest/
> [6] https://docs.openstack.org/glance/latest/
> [7] https://docs.openstack.org/neutron/latest/
> [8] https://review.openstack.org/#/c/477497/
> [9] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-gu
> ide/source/cli-nova-specify-host.rst
> [10] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-gu
> ide/source/compute-flavors.rst
> [11] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-gui
> de/source/cli-launch-instances.rst
> [12] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-gui
> de/source/cli-delete-an-instance.rst
> 


__
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] [nova][docs] Concerns with docs migration

[Matt Riedemann]

Now that Stephen Finucane is back from enjoying his youth and 
gallivanting all over Europe, and we talked about a few things in IRC 
this morning on the docs migration for Nova, I wanted to dump my 
concerns here for broader consumption.


1. We know we have to fix a bunch of broken links by adding in redirects 
[1] which sdague started here [2]. However, that apparently didn't catch 
everything, e.g. [3], so I'm concerned we're missing other broken links. 
Is there a way to find out?


2. The bottom change in the docs migration series for Nova is a massive 
refactor of the layout of the Nova devref [4]. That's something I don't 
want to do in Pike for two reasons:


a) It's a huge change and we simply don't have the time to invest in 
properly assessing and reviewing it before Pike RC1.


b) I think that if we're going to refactor the Nova devref home page to 
be a certain format, then we should really consider doing the same thing 
in the other projects, because today they are all different formats 
[5][6][7]. This is likely a cross-project discussion for the Queens PTG 
to determine if the home page for the projects should look similar. It 
seems they should given the uniformity that the Foundation has been 
working toward lately.


3. The patch for the import of the admin guide [8] is missing some CLI 
specific pages which are pretty useful given they aren't documented 
anywhere else, like the forced_host part of the compute API [9]. 
Basically anything that's cli-nova-* in the admin guide should be in the 
Nova docs. It's also missing the compute-flavors page [10] which is 
pretty important for using OpenStack at all.


4. Similar to #3, but we don't have a patch yet for importing the user 
guide and there are several docs in the user guide that are Nova 
specific so I'd like to make sure we include those, like [11][12].


[1] 
http://lists.openstack.org/pipermail/openstack-dev/2017-August/120418.html

[2] https://review.openstack.org/#/c/489650/
[3] https://review.openstack.org/#/c/489641/
[4] https://review.openstack.org/#/c/478485/
[5] https://docs.openstack.org/cinder/latest/
[6] https://docs.openstack.org/glance/latest/
[7] https://docs.openstack.org/neutron/latest/
[8] https://review.openstack.org/#/c/477497/
[9] 
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-guide/source/cli-nova-specify-host.rst
[10] 
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-guide/source/compute-flavors.rst
[11] 
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-guide/source/cli-launch-instances.rst
[12] 
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-guide/source/cli-delete-an-instance.rst


--

Thanks,

Matt

__
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