Migrate content to foreman-documentation

[maximiliankolb]

Hi everyone! I propose to migrate the content of the Satellite Performance Tuning docs to a new guide in foreman-documentation. I would love to create an initial PR of migrating the content.

From what I can tell, this should be possible license wise: copyright satellite-performance-tuning & license foreman-documentation.

There is also a thread in the Foreman Community Forum.

Please let me know if you have any concerns or if you think this is a good idea. Cheers!

[psuriset]

@mccun934 ^

[lzap]

I like the idea, however, this is on @psuriset and authors if they want to maintain the guide in ASCIIDOC. Most of our guides have more complex structure of reusable modules, but If you keep the guide in a single file I think it can be a very good editing experience for you.

FYI I am working hard on bringing navigation bar to our pages and finalize migrating of our old guide so very soon we can consider this to be the only documentation place for Foreman and Katello.

/CC @jhutar

[jhutar]

Hello! Almost all our testing is done on downstream Satellite (so our recommendations might not directly translate to Foreman and I fear Foreman doc community might be, justly, pushing us to test on Foreman which is not possible now given constraints we have) and main purpose if this repo is to have a doc for Satellite customers (so it would cost us additional work to rebrand the content from Foreman to Satellite every time we want to do a release). I know this is all solvable, just wanted to state minuses I see - thankfully this is not purely on me to decide :-)

[maximiliankolb]

In foreman-documentation, we are using asciidoc attributes to "brand" docuementation. For example, instead of "Satellite Server", we use {ProjectServer}. See also List of attributes for Satellite.

We also have different branches for different versions of Foreman, e.g. 2.5 which is used in Satellite 6.10.

[ehelms]

@jhutar I do not see this request as adding more work to the Satellite performance team or asking them to build tuning for upstream use cases. I would see this as:

1) Convert rst to asciidoc 2) Move the docs from here to a dedicated guide inside foreman-documentation (https://github.com/theforeman/foreman-documentation/tree/master/guides/doc-Performance_Tuning)

Expectations would be:

1) Satellite performance team contributes their usual updates to the performance guide in foreman-documentation 2) Upstream community may choose to publish an upstream version of the performance tuning guide 3) Both upstream community, Satellite performance team and Satellite docs team would work to maintain the guide, branding and if-else for different deployment types (e.g. foreman, katello, Satellite, orcharino)

[maximiliankolb]

@jhutar I do not see this request as adding more work to the Satellite performance team or asking them to build tuning for upstream use cases. I would see this as:

1. Convert rst to asciidoc
2. Move the docs from here to a dedicated guide inside foreman-documentation (https://github.com/theforeman/foreman-documentation/tree/master/guides/doc-Performance_Tuning)

I would take care of these two steps and create an initial PR once licencing has been sorted out from your side.

[jhutar]

Thank you @maximiliankolb !

Two more questions from my side:

Are there any other processes/rules we would have to follow when maintaining the guide in that repo?

Would we be able to make final decision in case of any disagreements?

[maximiliankolb]

Processes and rules: Yes. We have a couple of conventions, for example, modularize content if possible, see guides/common/modules; do not use Satellite or orcharhino, but {Project} instead etc, see attributes; use one line per sentence, and a couple more. Nothing out of the ordinary, but hey help us collaborate and maintain docs.

Final say: This is a community project, so we/you cannot blindly merge changes. However, you can open a PR at any time. If you make use of good git practices, there's nothing stopping us in reviewing your change and merging it in a timely manner. In the beginning, we might hint to certain conventions we adhere to, but I'm sure you'll be able to adjust easily. I doubt there will be much disagreement content wise, as you are the experts on performance tuning.

I had a quick look at a couple of commits (https://github.com/RedHatSatellite/satellite-performance-tuning/commit/c7e06444eaba61a12a756b34e7e9f8e090e98125, https://github.com/RedHatSatellite/satellite-performance-tuning/commit/763512b176e87e0b05b1e491c7dc8c702257f96b, and https://github.com/RedHatSatellite/satellite-performance-tuning/commit/02f4bfae4d47a924b6c00cb141173a1e17019dd1); most likely, we would have merged those PRs in a timely manner.

Anything to add @lzap ?

[Imaanpreet]

@jhutar I do not see this request as adding more work to the Satellite performance team or asking them to build tuning for upstream use cases. I would see this as:

1. Convert rst to asciidoc
2. Move the docs from here to a dedicated guide inside foreman-documentation (https://github.com/theforeman/foreman-documentation/tree/master/guides/doc-Performance_Tuning)

I would take care of these two steps and create an initial PR once licencing has been sorted out from your side.

Hello @maximiliankolb , so this is approved. You can create a PR request and please let me know if you need any help.

[maximiliankolb]

I have created a first draft PR to migrate the content: https://github.com/theforeman/foreman-documentation/pull/887

I will update my PR if you commit to devel in the meantime. Once it's merged, I will open a PR to add a link to the readme and kindly ask you to archive this/no longer accept contributions here and jump over to the foreman-documentation.

[maximiliankolb]

My PR in foreman-documentation is now ready for review: https://github.com/theforeman/foreman-documentation/pull/887 I appreciate any feedback/comments.

[jhutar]

Wow, awesome work @maximiliankolb ! Once merged, how would Satellite branded Tuning guide release process look like (at the end we need pdf with Satellite as a project name where needed)?

[maximiliankolb]

Thank you @jhutar

Once this is merged to master and then cherry-picked to 3.1 and 3.2, in Satellite downstream, you can (if you want to) provide this guide to customers as every other Satellite guide, for example Content Management Guide. The converted guide now uses asciidoc attributes, for example {Project} or {SmartProxy} which resolves to Satellite/Capsule in your downstream guide. I am sure colleagues such as @lennonka and @melcorr can help you internally to get this working.

[melcorr]

Would we be able to make final decision in case of any disagreements?

If you must insist on something specifically for Satellite, we can write an if statement displaying that specifically for Satellite in case there is any dispute about its relevance to the community.

[maximiliankolb]

We have merged my PR in foreman-documentation. It's live at https://docs.theforeman.org/nightly/Performance_Tuning_Guide/index-foreman-el.html

Would it be fitting to create a PR deleting all content on master and adding a note to the readme that all changes should go to foreman-documentation, except when you work on released versions for Satellite?

[Lennonka]

I can't tell, maybe this is a question for Shweta. I'll notify her. We'll get to it next week probably.

[jhutar]

Thank you @maximiliankolb for your hard work! I have did this: https://github.com/RedHatSatellite/satellite-performance-tuning/commit/aa764fbf8250daaa14f03540f1ff2a7b67e7c984 Hope it will do.

[maximiliankolb]

Awesome @jhutar! That will do for sure! Thanks for everyone's willingness the make the move happen.

[ShwetaNaresh]

@Lennonka Thank you for tagging me on this!

On Satellite, the Performance Tuning Guide is published as part of a KCS article for each major version. For easy access to the document, the Docs team helps to publish this PDF on the Satellite Product Docs page. This publishing is done a couple of days after the release date. As for the content ownership, I believe it lies with the Engineering team or the Performance team. Need to check on this. The PX and the Docs team did have a discussion on this to check if the PDF can be published on the Satellite Product Docs page on the GA date along with the other docs. This needs to be discussed further with the team who owns the content.

With the changes that are suggested as part of this PR, will we need to change the content ownership to the Docs team? If yes, we would need to involve Marie and Vendula for ack and resource management. If not, I would like to understand the impact on the Docs team.

[melcorr]

I would advise against changing the content ownership to the docs team @ShwetaNaresh Docs have never been able to maintain this, but now we have opened it for community contributions

[jhutar]

Hello @ShwetaNaresh and @melcorr . I assume we (Satellite Perf&scale team - ikau, isinghal and jhutar) are still responsible for publishing the guide even if it lives in upstream git repo now. I'm not aware of any request for ownership change. I consider results of this PR as a technicality only.

[ShwetaNaresh]

Hello Jan,

Yes, there is no change in the ownership for now. Satellite performance team continues to own the guide as they currently do.

Regards

Shweta

On Tue, May 24, 2022, 11:26 PM Jan Hutař @.***> wrote:

Hello @ShwetaNaresh https://github.com/ShwetaNaresh and @melcorr https://github.com/melcorr . I assume we (Satellite Perf&scale team - ikau, isinghal and jhutar) are still responsible for publishing the guide even if it lives in upstream git repo now. I'm not aware of any request for ownership change. I consider results of this PR as a technicality only.

— Reply to this email directly, view it on GitHub https://github.com/RedHatSatellite/satellite-performance-tuning/issues/33#issuecomment-1136447423, or unsubscribe https://github.com/notifications/unsubscribe-auth/AMBFMT3ZRICQF524OSWLZFTVLVCQHANCNFSM5IHF7DTQ . You are receiving this because you were mentioned.Message ID: @.*** com>