Open Stack

So, maybe a hybrid.

For example, have a standard "Contributing.rst", with fixed
template/content, that can link off to these other guides? (I feel
like this might be the original idea and I just missed the concept,
lol)

Maybe we need two templates. one for "contributing.rst" in the root
(boilerplate-ish) and one template for inside the documentation tree
("how-to-contribute.rst ???). This seems similar to what we have
today, but with a more formal template for the "how-to-contribute"
landing page.

To some degree there is a strange overlap here with the existing
"contributor" section of the documentation that has the gory coding
details, etc.

I still lean towards having the "slightly more verbose" version in the
documentation tree as then we can use the sphinx magic for glossary
linking, internal links, etc.

Michael

On Tue, Feb 25, 2020 at 2:56 AM Thierry Carrez <thierry at openstack.org> wrote:
>
> 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)
>