openstack-doc-core team mailing list archive

[Russell Bryant <rbryant@xxxxxxxxxx>]

On 07/12/2012 10:45 AM, Lorin Hochstein wrote:
> (crossposting to doc-core in case not everyone there has moved over to
> openstack-docs yet).
> 
> A question came up on this merge proposal: https://review.openstack.org/9494
> 
> In that proposal, I had created a "troubleshooting" section in the
> Networking chapter in the Compute Admin guide. Tom pointed out that we
> already have a whole Troubleshooting chapter and asked whether it made
> sense to just keep it in one place or split it across sections. I wanted
> to bring it up to the list to see what people thought.
> 
> I liked having it by section to have the Networking troubleshooting docs
> closer to the rest of the networking content. But I can imagine
> troubleshooting issues where it would deal with issues across multiple
> sections (e.g., some interaction between scheduling and VMs, for
> example), in which case that would make it harder to find the right
> content, since a reader might miss the troubleshooting section that
> solves their problem.

I like having it with the Networking chapter.  I think there are a
couple of general cases where people are going to be reading this
information:

1) They are reading through all of the docs to learn about OpenStack.
In that case, I think the troubleshooting information about a particular
topic is most useful with the rest of the information on the same topic.

2) Someone has hit a problem so they started putting it into Google.  In
this case, it doesn't matter that much where it is.  However, I still
think it makes more sense to have it in the Networking chapter.  Once
someone gets finished troubleshooting their networking problem, they
would likely be interested in reviewing other information on the
networking topic rather than other unrelated troubleshooting bits.

-- 
Russell Bryant