[TripleO] Branching our documentation
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.
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!
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.
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!
On Wed, Nov 3, 2021 at 1:35 PM Sean Mooney smooney@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.
John
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!
On Wed, Nov 3, 2021 at 2:15 PM John Fulton johfulto@redhat.com wrote:
On Wed, Nov 3, 2021 at 1:35 PM Sean Mooney smooney@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*.
On Wed, Nov 03, 2021 at 01:02:29PM -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.
Agreed! As it stands, even wallaby is quite different than victoria and earlier for the overcloud deployment and https://docs.openstack.org/project-deploy-guide/tripleo-docs/latest/deployme... isn't particular helpful after a point. I've tried to update it a few times with the "bare essential" steps but it feels so badly forked, I couldn't follow it.
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!
--
-- James Slagle
I think it's a great idea!
Cheers,
Brent
-- Brent Eagles Principal Software Engineer Red Hat Inc.
participants (4)
-
Brent Eagles
-
James Slagle
-
John Fulton
-
Sean Mooney