Foreman new-generation documentation

[lzap]

Everyone,

on behalf of Red Hat Satellite documentation team and involved Foreman engineers, I would like to show you preview of our effort to bring Satellite documentation sources, git and workflow to public. The ultimate goal is to move all Satellite guides to github and start working on Foreman documentation together with engineering and the community to improve both quality and quantity of the content.

What we have today is the Provisioning Guide, all text is updated to match upstream naming conventions and deployment. What’s still missing are images (diagrams) and broken links to other guides becuase they don’t exist. Other than that, the content is ready to be consumed by users and ready for patches from you guys. See the preview here:

https://lzap.fedorapeople.org/foreman-doc-ng/doc-Provisioning_Guide/

As you can see, structure of the documentation is very different from what we currently have. Instead separate documentation of individual plugins, the content follows individual topics, provisioning in this case. There are various chapters which are only relevant when a plugin is installed (e.g. Discovery, Katello, Remote Execution) and reader is informed about it with links on how to install additional plugins. We believe this is better than individual documentation plugin by plugin. Technically it’s possible to also generate plugin documentation separately, the long-term goal is to futher break chapters down into smaller pieces (modules) and assembly more artifacts (guides, books, pages).

What’s also different is format of the documentation, in order to allow smooth transition from internal Red Hat documentation team git and processes, we adopted their format which is AsciiDoc. We believe it’s also superior to markdown which works the best for short README document but it lacks many very much needed features. Feel free to take a quick look or send us a patch:

GitHub - theforeman/foreman-documentation: Documentation for the Foreman...

What you find in the git repository:

• Source code for the Provisioning Guide in asciidoc format
• Makefile to generate html, pdf and perform link checking
• Short README with more information on how to write and handle upstream vs downstream
• Travis job that verifies html/pdf build and performs link checking

We need your help:

• Incorporating what’s in our current documentation but lacking in the new one.
• Re-drawing diagrams or pictures in some hacker-friendly way so we can easily modify and regenerate them (dot, graphviz or similar)
• Helping to “upstreamize” another guide.
• Preparing a nice “template” with CSS for final presentation.

Next steps. We are going to pick another guide from Satellite documentation book set and “upstreamize” it in the same manner. We have chosen Provisioning Guide as the first one because in our current Foreman documentation we have pretty much zero coverage on this topic. However for other guides we will be also incorporating everything we have currently into the guides so if we choose to promote the new documentation officially, there are no gaps or nothing is lost in the process.

Also, we would like to ask Foreman infra team to help us setting up new domain docs.theforeman.org, virtual host and pipeline job that would build and push from master and stable branches into subdirectories like /master or /1.24. During the transition period, we plan to have a warning banner informing the user that it’s a WIP version of the documentation.

Thanks

[lzap]

@lzap

Also, we would like to ask Foreman infra team to help us setting up new domain docs.theforeman.org , virtual host and pipeline job that would build and push from master and stable branches into subdirectories like /master or /1.24 . During the transition period, we plan to have a warning banner informing the user that it’s a WIP version of the documentation.

Would like to ask @infra team for an opinion here.

Do you agree with the domain name?

Which tool/pipeline is the best for the job of building the site and copying it over to our new virtual host?

Thanks.

[John_Mitsch]

@lzap This seems like a really awesome effort and I’m happy to see documentation being added in the form of guides and workflows. I think this is a good direction for us to take. A couple questions and thoughts:

@lzap

The ultimate goal is to move all Satellite guides to github and start working on Foreman documentation together with engineering and the community to improve both quality and quantity of the content.

Are you thinking this will be only for “upstreamized” Satellite documentation or can we also add our own guides and workflow-based documentation to these docs in the future?

Also, we would like to ask Foreman infra team to help us setting up new domain docs.theforeman.org

How do you envision these guides being incorporated into theforeman.org? Will there be a new menu entry on the main page titled guides or something like this? I’m trying to understand how users will find these guides

Something that I think could be confusing if I was new to the Foreman project is our current documentation is on at theforeman/theforeman.org repo and this new documentation effort is at theforeman/foreman-documentation. I would expect theforeman/foreman-documentation to be the source of all documentation. I would vote for a name more like foreman-guides, but I think I may be late to the naming party for this one. Just my two cents

Talking with a documentation team at Devconf.us, they actually put downstream product and upstream documentation together in the same repo and had flags to signal if something was exclusive to one or the other. It may have been openshift, but I can’t remember at this moment. I’m not sure if this would work for us, but could be something we consider in the future and this effort would help make things easier.

Really glad to see this!

[lzap]

@John_Mitsch

Are you thinking this will be only for “upstreamized” Satellite documentation or can we also add our own guides and workflow-based documentation to these docs in the future?

The goal is really move all documentation effort from an internal gitlab to public github repository and continue from there in cooperation with Red Hat documentation team. Meaning, we are absolutely open to changing and improving the docs, adding new guides etc. However keep in mind that the Red Hat documentation team will do careful review and they have a policy and quality standard we must aim for.

@John_Mitsch

How do you envision these guides being incorporated into theforeman.org? Will there be a new menu entry on the main page titled guides or something like this? I’m trying to understand how users will find these guides

Open question, there’s still lot of to do and I don’t expect all guides to be finished this year. Therefore a separate site with some warning banner for now, maybe a link form our main site in GET HELP menu (Experimental docs) or something like that.

Long-term goal is to incorporate all good content from our current docs which we have at theforeman.org and katello.org and then replace those. Again, we are far from that but that’s my thikning.

@John_Mitsch

could be confusing

Absolutely, the new foreman-documentation repository have a directory called guides for a reason - we can move any other documentation-related content into other directories. If folks want, let’s do this for our old guides but we’d need to rewrite our CI deployment jobs and it could create confusion. Since the goal is to sunset the legacy docs in the future, I’d probably keep them as-is.

@John_Mitsch

had flags to signal if something was exclusive to one or the other

That’s exactly what we do. More details here:

foreman-documentation/guides at master · theforeman/foreman-documentation

Thanks for feedback!

[ekohl]

So this came up and I found it interesting.

It talks about 4 categories (tutorials, how-to, discussions and reference). Near the end it shows some examples. Since the author is involved in the Django project, it shows that example where they explicitly talk about the layout: https://docs.djangoproject.com/en/2.2/#how-the-documentation-is-organized

I’ve always thought the Django documentation was great and now I understand why: usually I looked for reference docs and I could find exactly those. Sometimes I wanted to learn something new and could look at howtos.

I know this is nothing new for the docs team and they want to head in a similar direction, but sharing for other developers or anyone wanting to contribute docs.

[lzap]

After watching the talk, I can say it’s very good however I believe these ideas were built for developer-facing software (a library, a stack, Django) rather then user-facing software like Foreman. That does not mean we should not take a lesson from there and map some ideas onto our case. I think our docs team have a similar setup but instead of 4 types of docs there are 2 (learn oriented, practice oriented) which is a bit more simple but quite similar.

[ezr-ondrej]

Well I don’t agree it’s developer-facing specific. I think that some Tutorials are something that we really are missing. Those people spitting on foreman over the internet are saying basically it’s hard to start and hard to understand the basic concepts. I believe that tutorials “Getting provisioning on vmware with foreman working” (basic foreman setup) followed by “Run ansible through foreman” (rex) would really benefit the community. We are missing the entry points to the project. It’s really hard to get from installed foreman (even the install is really hard) to a working foreman and some guidance of Tutorial to show the power of foreman in easy steps would be awesome.

[mcorr]

I believe that tutorials “Getting provisioning on vmware with foreman working” (basic foreman setup) followed by “Run ansible through foreman” (rex)

With a few months, and a little bit of luck, this is something that the upstream docs should be able to provide. At the moment, we are migrating the core guides as they exist, then with some refactoring, we will be able to provideexactly whatever combination and sequence of instructions that we see community members need.