[TripleO] Branching our documentation

James Slagle james.slagle at gmail.com
Wed Nov 3 19:01:16 UTC 2021


On Wed, Nov 3, 2021 at 2:15 PM John Fulton <johfulto at redhat.com> wrote:

> 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 is correct. stable/wallaby would be for Wallaby and all prior
versions. Essentially, as the docs are now.
Master would be Yoga only. When Yoga is done, we'd branch stable/yoga and
master would become Z*.

-- 
-- James Slagle
--
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20211103/51483f31/attachment.htm>


More information about the openstack-discuss mailing list