New git repository for WIP documentation


#1

Hello,

me and @mcorr would like to do proof of concept of taking a Satellite guide (Provisioning Guide) written by Red Hat documentation team, putting it on github and making necessary changes so it can be used by Foreman and Katello users. I would like to do this in the correct repository from the very start so we also have a full history of PR discussions, therefore I would like to ask for creation of theforeman/foreman-documentation git repository so nothing gets lost or there are no redirections in the future.

We are targeting to show you first results probably on the next demo (not the one this week). Then we can evaluate and decide if this is a viable option and continue from there or ditch this effort. I have high hopes in this however.

Anyone is welcome to participate. In the initial phase, we would like to review Provisioning Guide and add all missing information from our upstream documentation, correct some parts or restructure some sections. You can participate too! Ping me or Mel if you want to jump in this early.

For better docs!


#2

Hello,

I think this effort that we are trying to do here will take our project and community to the next level altogether :slight_smile: I see issues with the first time contributors getting started, updating documentation as a challenge for the community, and many more to be addressed while looking at this effort!

I know this will take time and a huge amount of work but it seems to be worth the while. Lot of eyes on this would make the documentation a very solid one, so if anyone has little time to spare then please join us in this effort and let’s make our documentation more awesome than it is now :slight_smile:

Thanks,


#3

I’ve created https://github.com/theforeman/foreman-documentation and https://github.com/orgs/theforeman/teams/documentation. Currently only @lzap is a member, but he’s a group maintainer so can add members. Let me know if you need help with anything.

Should we give the docs team permissions on our website repository.


#4

@lzap Sorry if I missed some previous discussions - where will users ultimately find this guide? on theforeman.org or the github repo itself?


#5

Hey John,

this is going to be decided by Foreman community, for now this is WIP and temporary results will be presented on Discourse (probably as links to some temporary sites out of theforeman.org). I want to do site-by-side comparison of the Provisioning Guide against Foreman, Katello, Discovery and Bootdisk plugin documentations. And for that, we need to have the content available. Stay tuned.


#6

Thanks Ewoud.

Not for now, let’s work on the prototype first, then do decision on how to approach the rest and only then it would make sense to work in both repositories. For now this is totally separate repository with completely new content.


#7

One more detail, I can’t add Mel until she is added to our Foreman organization: https://github.com/melcorr Any objections against adding her? Of course this means she need to enable 2FA (do we actually enforce this so users can’t log in without enabling it)?


#8

I sent @mcorr an invite to the org and the team, and also added @rabajaj and @Ori_Rabin to the team.

Please add a note in the README file making it clear that the repo is a POC and pointing to this discourse discussion. For the future, it might be better to create POCs on personal repos, then if accepted we can migrate them to the foreman organization.


#9

I don’t mind the visibility. It also means we as GH admins can assist with repo configuration. However, I strongly agree we should clearly mark the intent/status of repositories in READMEs.


#10

Sounds good, though I think foreman-documentation is a bit misleading as I would expect all the foreman documentation to live there, but it sounds like some clarification in the README will help there.

I’ve been thinking about making guides like this myself and I would love to see them on theforeman.org in a workflows section or something like that. A place to have Foreman + plugin workflows that devs and the community can contribute to would be great, especially if its on the main Foreman docs pages.

Looking forward to seeing this develop, thanks for the effort!


#11

That has been already done yesterday in my local repo, however I am awaiting confirmation from the Red Hat legal team and then I can finally push. It will take few weeks however to do necessary changes and modularize the documentation so it’s more usable by Foreman/Katello users.

That’s actually the ultimate goal - all documentation in one git repo in a friendly format, easy to start with, easy to build high quality content in HTML/PDF and eventually the only place with all Foreman, Katello and plugins documentation. However it will be a long and difficult journey. Which does not mean we can’t start.

If anything fails, like my arm will start hurt (again) or folks dislike how it looks then we can simple delete the repo and nobody is confused again.


#12

I prefer updating the README with the reason for closing and archiving, but that’s an implementation detail (and the reason I already created it rather than bikeshedding).