Open Stack

Kendall Nelson wrote:
> There is some debate about where the content of the actual docs should 
> live. This grew out of the discussion about how to setup the includes so 
> that the correct info shows up where we want it. 'Correct' in that last 
> sentence being where the debate is. There are two main schools of thought:
> 
>     1. All the content of the docs should live in the top level 
> CONTRIBUTING.rst and the sphinx glue should live in 
> doc/source/contributor/contributing.rst. A patch has already been merged 
> for this approach[1]. There is also a patch to update the goal to 
> match[2]. This approach keeps all the info in one place so that if 
> things change in the future, its easier to keep things straight. All the 
> content is also more easily discoverable when looking at a repo in 
> GitHub (or similar) or checking out the code because it is at the top 
> most level of the repo and not hidden in the docs sub directory.
> 
>      2.  The new patch[3] says that the content should live in 
> /doc/source/contributor/contributing.rst and a skeleton with only the 
> most important version should live in the top level CONTRIBUTING.rst. 
> This approach argues that people don't want to read a wall of text when 
> viewing the code on GitHub (or similar) or checking it out and looking 
> at the top level CONTRIBUTING.rst and as such only the important details 
> should be kept in that file. These important details being that we don't 
> accept patches in github and where to report bugs (both of which are 
> included in the larger format of the content).
> 
> So what do people think? Which approach do they prefer?

I personally prefer a single page approach (school 1). That said, I 
think we need to be very careful to keep this page to a minimum, to 
avoid the "wall of text" effect.

In particular, I think:

- "Communication" / "Contacting the Core team" could be collapsed into a 
single section

- "Task tracking" / "Reporting a bug" could be collapsed into a single 
section

- "Project team lead duties" sounds a bit overkill for a first-contact 
doc, can probably be documented elsewhere.

- Sections could be reordered in order of likely involvement: How to 
talk with the team, So you want to report a bug, So you want to propose 
a change, So you want to propose a new feature.

> I am anxious to get this settled ASAP so that projects have time to 
> complete the goal in time.

Agree it would be good to come up with a consensus on this ASAP. Maybe 
the TC can settle it at next week meeting.

-- 
Thierry Carrez (ttx)