[all][PTL][tc] U Community Goal: Project PTL & Contrib Docs Update #3
thierry at openstack.org
Tue Feb 25 10:53:16 UTC 2020
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. There is also a patch to update the goal to
> match. 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 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
- "Task tracking" / "Reporting a bug" could be collapsed into a single
- "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)
More information about the openstack-discuss