Code & Documentation Contributor Guide in contributor-guide

[Alexander Kjeldaas]

This bug tracker is for errors with the documentation, use the following as a template and remove or add fields as you see fit. Convert [ ] into [x] to check boxes:

- [x] This doc is inaccurate in this way: Incredibly complex
- [ ] This is a doc addition request.
- [ ] I have a fix to the document that I can paste below including example: input and output.

If you have a troubleshooting or support issue, use the following resources:

 - Ask OpenStack: http://ask.openstack.org
 - The mailing list: http://lists.openstack.org
 - IRC: 'openstack' channel on Freenode

-----------------------------------
Release: on 2018-03-09 01:23
SHA: 1e51e48349f3ed86a76ca57207d70ec9f27f79e1
Source: https://git.openstack.org/cgit/openstack/contributor-guide/tree/doc/source/code-and-documentation/index.rst
URL: https://docs.openstack.org/contributors/code-and-documentation/index.html

This is a bug report for https://wiki.openstack.org/wiki/Cinder

BUG 1: The wiki page for Cinder must prominently discuss the difference between "Cinder" and "Cinderv2". Specifically:
  - Which is the latest version?
  - What are the differences.

This is important as this is the top result on google for "openstack cinder".

META BUG 2: The email address of something called "PTL", the core team and all of that stuff is extremely unimportant. It actively discourages reading of the wiki as it's 99.999% certain that the reader is not looking for that information. The information must be presented in pyramid style.

META META BUG 3: Documentation bugs and feedback must be possible to give in less than 10 seconds. How to file bugs/changes to the wiki must be clearly specified. The quality is so poor that it's extremely important that people actually give feedback. In order to do so now, I had to follow these steps:

Step 1: Login, including creating a Ubuntu One account.
Step 2: Navigating to a few random pages with lots of text, like https://docs.openstack.org/queens/ and https://www.openstack.org/community
Step 3: Finding https://docs.openstack.org/contributors/ which is another wall of text.
Step 4: Finding the link " found an error? report a bug" mostly hidden at the bottom of the page.
Step 5: Another login(!)
Step 6: Another page to enter a "summary".
Step 7: Then navigating the above text which asks me to put an [x] in some boxes.

We're talking about 15-20 steps in total which only an extremely dedicated user would even manage to navigate, and an effort likely exceeding 5-10 minutes. 95% of this must be cut out, at a minimum. The feedback system is EXTREMELY opinionated, expecting only a very narrow type of feedback. The wiki page is clearly not a wiki and strongly discourages editing/feedback.

[Frank Kloeker (f-kloeker)]

Hi Alexander,

thanks for the bug report. You mixed up OpenStack Wiki and OpenStack Documentation.
First of all: This bug space here ist for OpenStack Contributor Guide (https://docs.openstack.org/contributors/). So we are not able to help in this section. What are you looking for is
https://docs.openstack.org/cinder/ If you click there on any pages on the bug report button on the right site, the report will automatically route to the right section. In this case: cinder

The Wiki Page what are you mentioned is more for project team work and not for documentation. You can find there typically information about team structure and team communication. Sometimes it's easier to reach a team member or join a meeting to discuss a specific topic like that.

I can understand your thoughts and that you are angry. But we are mostly part-time contributor with limited resources and any help is still welcome. For the Wiki Page I've added a link to the documentation. So hopefully it's easier to find information now.

Frank

[Ian Y. Choi (ianychoi)]

I mentioned this page to cinder team via IRC. Hopefully, cinder team would update wiki information soon :)