We have a few toolkits in the making to help the community. What we need to decide for each:
Where is the best place to source this information? (aka what github repo or other option where it will be easily editable by contributors). Options are:
In an appropriate github repo or new repo (if nothing already relates to the toolkit)
In this forum as a wiki
Where should we publish? We will likely include a link to these toolkits from the website if we don’t choose to publish directly on the website. The publish options are:
On a RTD site if no other existing RTD or documentation site already exists
This toolkit is curated list of documents and resources to help the meetup organizers to plan and execute the Ansible meetups. The meetup toolkit currently resides in the existing ansible-community/meetup repository.
Documentation toolkit
This toolkit can assist projects in determining what markdown language to write in, how to publish to RTD as an Ansible ecosystem project, and guidance on how to structure the guides necessary for the project. It can also act as an aid to technical writers and other documentation contributors but is not a replacement for the existing Ansible style guide.
New project onboarding toolkit
This toolkit doesn’t exist yet but the goal is to provide new Ansible projects with the resources and information they need to decide on the appropriate github repo and intial setup requirements, setting up matrix rooms and forum tags. It will also link to the Documentation toolkit as an important resource for new projects.
@oranod Well the intended audience for the documentation toolkit isn’t the ansible core/package docs contributors. It’s for new projects or other ecosystem projects to adopt a common style, as well as guidance on how to set up their repo for sphinx or mkdocs and publish to ReadTheDocs site.
So I see that documentation toolkit to have two parts
a ‘static page’ that has all the how to do this, and how to do that, and a set of proposed guides that most projects should have.
a set of template/example files in .md and .rst that a project can just grab and start writing.
That set of template files could go in ansible/ansible-documentation, but I think we want to make it as easy as possible for a new project to just grab the docs ‘scaffolding’ so to speak and apply it to their repo. I don’t know enough about git/github to know if it’s easier to grab from an existing larger repo like ansible/ansible-documentation or if it’s easier to have an example docs repo that just has this templating.
I think we community website could host the static page and point to whatever repo has the scaffolding/template files.
Alternately, the community website could have a ‘toolkits’ page that just summarizes all the toolkits/process docs and has a pointer to …whereever we want to publish the static pages. But I wouldn’t want to point just to a raw rst page in github so to speak.
@samccann I just feel like ansible-documentation avoids more fragmentation. I don’t know if contributors would necessarily see it as the place for core/package docs only. Plus putting the toolkit in that repo means it’s likely to get more review from folks who might not necessarily be involved with the ecosystem but would have ideas on all the tooling and scaffolding. It also puts the source for the writers toolkit close to the source for the writers contribution guide, which might make it easy enough to move things around and condense a few bits.
Also I think it would be possible to put the base scaffolding in the docs repo and provide a command like cp -r /ansible-documentation/writers-toolkit/mkdocs-scaffolding/* new-project-root/
Having that in the docs repo also means we can run our new linters and formatters over the scaffolding…
@samccann I take your point though and the docs repo might not be a perfect place but it seems the most logical to me. Totally willing to be corrected on that.
I think a separate examples/scaffolding repo would be better. I agree that it’s easier to work with for both contributors and consumers, and we want to avoid the One Repository Being Used For Too Many Things problem that we’ve had to deal with in the past.
The original thought was a place someone could start a new Ansible project repo. I could add the docs scaffolding there, but again, I wonder if that’s overloading that project-template repo?
I think it depends on how we include it on the website, do we lift the whole toolkit and drop it in there? (not my preferred way - we’ll need several webpages with nesting and breadcrumbs probably), or do we provide an overview of the toolkit on the website and then link to the various milestones/templates that reside in the current repo? or do we want a separate RTD site for it (and linked from the website)?
I think it also depends on what we decide for the other toolkits, to provide a consistent experience.
For me, the publish part is key. The source location doesn’t matter too much - people will be less likely to find the repo on GitHub than be directed to it from the toolkit or by a contributor. So this will be decided by other factors, I think.
So then the question becomes “we have a bunch of pages and possible downloadable resources, how do we host that?”. I think we need to be flexible here - we know of several toolkits in development (Meetup, Docs, etc), and more that may come (New Project, Mentoring & Ambassadors), and some may have a natural home (eg Docs toolkit could easily live in/near the docs repo).
@samccann@oranod One thing we talked about was what to do (long-term) with the “unversioned” docs like this page - pages that don’t track an Ansible version and indeed are harmed by doing so[1]. It seems to me that both our toolkits and our processes (which today exist across docs, hackmad, github wikis, and more) would benefit from an unversioned docsite of their own. Should we make one? Many of the toolkits would then have a natural home.
That would then naturally lead to linking to that from other places (the website, meetups, forum etc)
if I look at the 2.9 docs I still want to know where the community is today↩︎
Regarding the Meetup Toolkit I have the following suggestion. Leave the Toolkit as it is till we get the website and which all part of the Toolkit we want to live in the Website get sorted. In the meantime we get some invested users of the Toolkit. Then they also can chime in the conversation regarding where Toolkit’s final home would be.
We talked about this in the DaWGs (documentation) meeting earlier this week and the proposal is to publish toolkits to Read The Docs from their existing repos. We can then link to those docsites from…wherever we want (forum, other documentation, website, etc).