Should we have templates available for Ansible documentation?

Project Discussions
1

I stumbled across The Good Docs Project from a Fedora post, and thought it might make for an interesting docs discussion.

TL;DR; - Should we have a small set of .md or .rst files that help developers or other project contributors structure good guides?

We could use the templates in that project or fork/create a smaller set of our own for Ansible ecosystem projects. For the most part, these templates help the author include important parts of documentation that they may not think about at the time they create a new user/developer/contributor guide and so on.

We could create a Documentation Writers toolkit that would explain them as well as cover other details that help a project have quality documentation.

Thoughts?

4 Likes
2

I think it’s a great idea, at least personally I’d appreciate having some templates as guides to help me get started!

1 Like
3

Yeah this sounds like it should be part of that writer’s toolkit so +1 from me.

1 Like
4

100% yes. Back in the Openstack Puppet community, we were providing a cookiecutter template for our puppet module, basically run that commands and you have a puppet module that does an hello world with all the opinionated practices that specific group followed.

It was really easy to start with and we’ve witnessed people coming to our IRC channel then, showing end to end working modules and asking for feedback.

The lower the entry barrier is to start anything, the better

1 Like