As I dip in and out of ansible I find it quite hard to find information
outside of the main documentation (which is a great base).
Part of the problem is that searching for stuff picks up mailing list
items which are (say) 3 months old - or several generations - and the
ansible work has changed since then. The mailing list currently has a
lot of good stuff on it - but its passing by quickly, and finding stuff
in there is rather hard.
So, is there a case for running something more wiki-like for storing
current information?
The problem with this is that wikis can get clogged with old stuff, so
they need a degree of gardening frequently.
Or is there some better mechanism to collate knowledge? Maybe with a
way to upvote/downvote info so its easier to retire off the old stuff?
The main documentation is pretty easy to get at - and the target
audience should be comfortable with a git clone/edit/push setup, but
currently there are not good places to add non-core documentation - and
that howto fix small problems docs are often the best things to give
folks hints...
Sorry - bit of a ramble, but hopefully may help kickstart something...
Nigel.
The documentation website is part of the ansible main repository, to which you can contribute by means of pull requests.
Serge
Yeah I am not a huge fan of Wikis.
They tend to collect out of date or updated information.
If you find something mentioning, as Serge said, please take time to
at least file a ticket about it or send a pull request to the
docsite/rst/*.rst files.
I don't think there's a lot missing, but there are probably a few
things scattered around that could be clarified.
--Michael
Michael,
Yeah I am not a huge fan of Wikis.
neither am I: most Wikis suck because they quickly grow stale.
Nevertheless, Nigel is right: it's difficult to find auxilliary info
on Ansible which isn't "ancient".
Would you be willing to add a Wiki to the Github Ansible repo? (Admin,
Options, Features, Wikis checkbox)? We could then give it a try. Maybe
Nigel and I can start on that...
If it takes off (and is maintained), great. Otherwise you kill it.
Github Wikis can have edits restricted to collaborators (same page in
Admin panel) or be open to public edits). They support history,
pull-requests, etc. I'm no specialist on this, but it seems to me as
though this platform is possibly best-suited for Ansible because of its
Github hosting anyway. [e.g. we can reference issue numbers, etc.]
Might be worth a try.
-JP
Would you be willing to add a Wiki to the Github Ansible repo? (Admin,
Options, Features, Wikis checkbox)? We could then give it a try. Maybe
Nigel and I can start on that...
I'm not against it if we limit scope -- it should not repeat docs, for
one, and things that should be docs should be in docs.
Bugs are not things that go on the Wiki -- those go in bug reports.
We can put all that in the front page, though I can definitely
use some help curating it.
Etc.
But as for a way to do a set of instructions about how to do certain
things, that sounds perfect, yes.
I'll set one up shortly.
If it takes off (and is maintained), great. Otherwise you kill it.
Github Wikis can have edits restricted to collaborators (same page in
Admin panel) or be open to public edits). They support history,
pull-requests, etc. I'm no specialist on this, but it seems to me as
though this platform is possibly best-suited for Ansible because of its
Github hosting anyway. [e.g. we can reference issue numbers, etc.]
I've been fine with them being open to anyone with a github account in the past.