linux-system-roles
add example how to run/use the role
The README is missing some basic information about how to install/use the role. It should probably mention how to use ansible-galaxy, what is needed to run from GIT and how to invoke the examples with ansible-playbook.
The role READMEs are currently more a reference documentation, making sure every option is properly described. They are not suitable as task-oriented HOWTOs / user stories. They could be expanded to cover this as well, but since they are already long enough, I believe this is better covered in a separate document, which would also include this basic information you are asking for. We have been working on this with @t-woerner.
The advantage of a separate document would be also that it can be in another format than Markdown (like asciidoc).
The information about how to install and invoke an example using ansible-playbook is already given at https://linux-system-roles.github.io/ , Wouldn't it be better to build on that since it will be common for all roles ?
The information about how to install and invoke an example using ansible-playbook is already given at linux-system-roles.github.io , Wouldn't it be better to build on that since it will be common for all roles ?
Good observation. A link to this documentation from the network role's README might be good and then the other documentation could be extended.
The information about how to install and invoke an example using ansible-playbook is already given at linux-system-roles.github.io , Wouldn't it be better to build on that since it will be common for all roles ?
Good observation. A link to this documentation from the network role's README might be good and then the other documentation could be extended.
+1 - please feel free to submit a PR to https://github.com/linux-system-roles/linux-system-roles.github.io/
I think it will be better to restructure the site first .
The contributing and How to install section have their own sub pages and the corresponding sections be removed from the landing page .
Since we already have a detailed contributing I think putting that up at the site should be better as well since that is also common for all the roles .
We can remove anything that might be specific to a single role(this can remain in the role's contributing document) and keep the rest on the site
or
We can specify/mention if something applies to only a single role (currently I only see code structure in this category ) and then maybe specify this for all roles. This should help in reducing duplicates and provide a place for common resources .
The how to install/use page can then be extended with whatever information is required