[TripleO] Branching our documentation
johfulto at redhat.com
Wed Nov 3 18:15:25 UTC 2021
On Wed, Nov 3, 2021 at 1:35 PM Sean Mooney <smooney at redhat.com> wrote:
> On Wed, 2021-11-03 at 13:02 -0400, James Slagle wrote:
> > Hello TripleO Owls,
> > Our documentation, particularly the deploy guide, has become overly complex
> > with all the branches that TripleO has supported over the years. I see
> > notes that document functionality specific to releases all the way back to
> > Mitaka!
> > In ancient history, we made the decision to not branch our documentation
> > because the work to maintain multiple branches outweighed the effort to
> > just document all releases at once in the same branch.
> > I think the scale has now tipped in the other direction. I propose that we
> > create a stable/wallaby in tripleo-docs, and begin making the master branch
> > specific to Yoga. This would also mean we could clean up all the old notes
> > and admonitions about previous releases on the master branch.
> +1 as some one that very really uses ooo and who always need to look at the documentation
> when i do try to use it i find the current docs very hard to parse due to all the differnt release annotations
> inline. the ooo docs themselve are not actully that extensive upstream and you can read all or most of them in one afternoon
> but parsing them and the parts that apply to the relase you are trying to deploy is a lot more effort then the branached
> docs in other projects. i think this definetly help the new user and might also help those that are more expirnce with ooo too.
So stable/wallaby would have the notes and admonitions about previous
releases (which are useful if you're using an older version)?
Then we could then make a smaller main branch which is leaner and
focussed on Yoga?
That sounds good to me. I'd be happy to help with the clean up after
the branch is made.
> > Going forward, if you make a change to the docs that applies to Yoga and
> > Wallaby, you would need to backport that change to stable/wallaby.
> > If you needed to make a change that applied only to Wallaby (or a prior
> > release), you would make that change only on stable/wallaby.
> > I'm not sure of all the plumbing required to make it so that the OpenStack
> > Wallaby deploy guide builds from stable/wallaby, etc, but I wanted to get
> > the idea out there first for feedback. Please let me know your thoughts.
> > Thank you!
More information about the openstack-discuss