| 2016-09-09 01:29:37 |
Brian Moss |
description |
This issue has been split from https://bugs.launchpad.net/openstack-manuals/+bug/1479166 to capture the request of Martin Paulo in comment #3
---
As a developer the OpenStack documentation can be very frustrating. Let me try to explain...
Faced with a problem, I turn to Google, which gives me links that look as though they might help me. Say one is to a blog posting, or to Stack Overflow. This article provides good information, but contain links to the OpenStack documentation for more detail. So I click on the link, only to find that the page no longer exists.
So I turn to Google again, trying to find this new information. But Google itself either contains links that are either outdated (so I have to go the cache, not always guaranteed to work) or that take me to pages that exist: but turn out to be part of some older documentation set (I haven't experienced this for a while, so don't know if this is fixed or not). Clicking around the older documentation set results in total confusion as you get launched into new parts of the site. And you don't find what you are looking for...
Could you please migrate the documentation to stable urls (as per http://www.w3.org/Provider/Style/URI.html)? I suggest the Django documentation as an example to follow. See https://docs.djangoproject.com/en/1.4/ vs https://docs.djangoproject.com/en/1.8/ vs https://docs.djangoproject.com/en/ for an example of how they manage this...
This would have the added advantage of allowing people who are on older versions of OpenStack to still have easy access to the relevant documentation.
Thank you! |
This issue has been split from Bug #1479166 to capture the request of Martin Paulo in comment #3
---
As a developer the OpenStack documentation can be very frustrating. Let me try to explain...
Faced with a problem, I turn to Google, which gives me links that look as though they might help me. Say one is to a blog posting, or to Stack Overflow. This article provides good information, but contain links to the OpenStack documentation for more detail. So I click on the link, only to find that the page no longer exists.
So I turn to Google again, trying to find this new information. But Google itself either contains links that are either outdated (so I have to go the cache, not always guaranteed to work) or that take me to pages that exist: but turn out to be part of some older documentation set (I haven't experienced this for a while, so don't know if this is fixed or not). Clicking around the older documentation set results in total confusion as you get launched into new parts of the site. And you don't find what you are looking for...
Could you please migrate the documentation to stable urls (as per http://www.w3.org/Provider/Style/URI.html)? I suggest the Django documentation as an example to follow. See https://docs.djangoproject.com/en/1.4/ vs https://docs.djangoproject.com/en/1.8/ vs https://docs.djangoproject.com/en/ for an example of how they manage this...
This would have the added advantage of allowing people who are on older versions of OpenStack to still have easy access to the relevant documentation.
Thank you! |
|
