Document all template parameters

[lzap]

WIP document here:

https://docs.google.com/spreadsheets/d/1ryY6igvVX08-5EPZf1WiaEDArhY2N7luq-55Px0Qru0/edit?usp=sharing

[melcorr]

Hi @lzap

As I've mentioned before, the chance of this type of documentation happening is very slim.

I think that these type of reference docs are best baked into the UI, in the same way the API docs and the way the templates have a help tab already.

What I would suggest is that these get documented in either the web UI or in the hammer commands, then we educate the user on how to find a list of these at all times, similar to what has been done with report templates docs. To move this forward, it should be as a "teach a man to fish" approach.

https://docs.theforeman.org/master/Managing_Hosts/index-foreman.html#proc_creating_a_report_template

If you look here, the emphasis is always on education to enable the user to find what they need themselves:

https://docs.theforeman.org/master/Managing_Hosts/index-foreman.html#appe-Red_Hat_Satellite-Managing_Hosts-Template_Writing_Reference

[lzap]

I think that these type of reference docs are best baked into the UI, in the same way the API docs and the way the templates have a help tab already.

We will be actually adding this into the project, but I think it would be a good appendix. Similarly we will want to add all options of our installer. Both of these can be show via a command.

I understand your concern of preventing the content from going out of sync, I would never suggest such thing if there wasn't automated way of generating this. That was the idea.

[melcorr]

I think that these type of reference docs are best baked into the UI, in the same way the API docs and the way the templates have a help tab already.

We will be actually adding this into the project, but I think it would be a good appendix. Similarly we will want to add all options of our installer. Both of these can be show via a command.

Excellent.

I understand your concern of preventing the content from going out of sync, I would never suggest such thing if there wasn't automated way of generating this. That was the idea.

If we are autogenerating it, is this the correct place to have a ticket for it? Most of the docs created here are written by hand :-)

[lzap]

It was a ticket for myself, but I don't mind closing this.

[ekohl]

If we are autogenerating it, is this the correct place to have a ticket for it? Most of the docs created here are written by hand :-)

For what it's worth: I think that autogenerated documentation can be useful as reference documentation. As long as it's clearly marked as such, it can be useful. For example, keeping a list of all settings and what they mean is useful reference documentation. If you can link to each individual setting, it's useful when supporting someone.

We have also seen that a manual list is often forgotten. Generating it from sources is a good way to keep it in sync.

[melcorr]

I agree completely, @ekohl !

@lzap I don't mind it being open here, but just wanted to clarify the how to solve this.

[ekohl]

https://github.com/theforeman/theforeman.org/tree/gh-pages/scripts has some scripts to generate parts. These are then mentioned in the release procedures (like here. That's how we can keep things up to date.

You can choose a directory structure where there's something like a generated directory that only has generated content to make it easier to distinguish them.

[lzap]

You can choose a directory structure where there's something like a generated directory that only has generated content to make it easier to distinguish them.

Good idea, thanks for the links I will use this know-how when starting on moving installation guide here hopefully this week.