Looks like many of the plugin manuals haven’t been updated in a while.
Some examples from the more popular plugins:
Plugin
Latest manual version
Current plugin version
Ansible
3.x
5.0
Discovery
15.0
16.0
OpenSCAP
1.0
3.0
Remote Execution
1.7
3.1
Salt
12.0
13.2
Tasks
0.8
1.0
Templates
6.0
8.0
Perhaps some of these didn’t have many changes that need the manual to be modified, but that is probably not the case for most. In any case, this doesn’t look promising for a new user who is looking for documentation on a plugin and doesn’t find a manual for the current version.
I don’t have a good idea of how to handle these gaps, other than bringing it to the attention of plugin maintainers and the rest of the community. What do others think?
This might also be a good option for people who aren’t programmers to contribute - updating the documentation is relatively straightforward. How can we direct new contributors in that direction?
This is matching a discussion I had with a customer earlier this week. While I would not recommend enforcing a policy or something similar, I had several events in the past with new features of Foreman missing documentation and the situation with plugins is much worse, so I really like you bringing more awareness to this.
I think there are quite many reasons for this situation that could be tackled from different directions. Some of them we might be able to tackle without the plugin maintainers getting contantly “nagged” on to update their documentation, but the essence most likely will boil down to that.
People just don’t like to write documentation. This is probably the most important one and one that about all community driven projects suffer from. We probably cannot change this.
Awareness. I would guess most users are not even aware of the fact the documentation can actually be forked an contributed to. The only page on theforeman.org that I found where the “Fork me on GitHub” banner was shown was the actual “Contribute” page, and that only led to the theforeman organization over on GitHub. The reference to the repo for the actuall page is a tiny link in the footer, burried under a lot of other content. I remember it took at least me quite some to figure out this repository even existed.
Documentation for how to write Documentation. While the readme for the theforeman.org repo has some basic coverage for how to do testing of the new pages, and states it is “just Markdown”, there is absolutly no documentation of the different macros that can be used, or at least I could not find any. Some of them like the version makro are quite important if you want to stay sane writing documentation, and I could not find a list which ones are even available.
Expectation. Users who go to documentation usually expect help with a certain topic, not to write it themselfes. Once one would be in the position to contribute documentation, they usually don’t go there anymore and so don’t even realize there is a problem. Also, a lot of people probably don’t even feel like they can help, because they have not written the code and so cannot say for sure if they would even document the correct thing. They just expect the author of the software to do the documentation, simply because they are usually the only ones fully capable of that task. The fact that most users are usually lagging behind in versions (at least one or two releases due to corporate/organizational update policies) makes this only worse.
We are facing similar issues on the support side. There are a lot of people posting questions to the forums, but looking back at the past two weeks of activity in the Support category, I mainly see the same ~10 people actually replying, most of them are in some way also related to the development.
5. How do people search for documentation? I can not tell for everyone, but a lot of people probably just google their problem and then “stumble” upon some docs. This might be the official docs or the Readme of the related repository, which is usually at least somewhat up to date. I’m guilty of that myself, even if I know I’m look for the official docs for a plugin, even if it’s just because I’m not able to remember which Plugins have docs on the site and which ones just link to their readme anyways.
Some suggestions I’ll leave here for further discussion:
Make people more aware that the documentation can easily be contributed to, like putting a “Fork me on GitHub” banner direktly in the header bar of documentation sites or something.
Wild suggestion: If a plugin has documentation on the site, check for it beeing updated when new versions are submitted for the software repos. If I remember correctly, updating the plugins repositories is also handled in some way via GitHub merge requests (or at least this is what I understood), so maybe that can be automated via some GitHub bot? This might be dangerous territory though, since it might lower peoples effort to contribute plugin updates or official docs at all.
Maybe implement an “official” documentation week every so often (like the testing week before branching for RC), where people are explicitly encouraged to update documentation and reminded to do so. This would have the added benefit of also spreading awareness for this topic as some sort of side effect.
The idea is to create consistent experience that is not structured technically (plugins, modules, parameters) but from the user perspective. It will be more opinionated, it has to be, but a single place with all the required information will be much better experience.
Anyone can help! We are currently in the process of converting Red Hat Satellite documentation into upstream Foreman docs. Instructions how this can be done is in the README, if anyone can help just let Mel know:
Other tasks:
Implement “Fork me on GitHub” button (AsciiDoctor template must be modified, CSS/HTML skills needed)
Move content that is present in our official docs but not in the new documentation
Move plugin documentation to the new docs (not all guides are available yet tho: installation and provisioning are ready tho)
Write new chapters, there’s so much to cover!
Find issues, fix them. The format (AsciiDoc) is easy to understand, a PR is really quick.
