Where should we document the new play argspec?

Project Discussions
, ,
1

So if you haven’t seen it yet, play argument specification validation is coming in ansible-core. There’s also a draft doc for this, with an open question for us -

How/where should we add documentation for this? The current draft docs PR includes it in the intro to playbooks page, under the validating playbooks heading.

We could keep it there and link to it from other places, as the PR suggests.

Do you have other thoughts on where this new feature should be documented?

4 Likes
2

I think this would be better suited in a subsection of “Working with playbooks” (Working with playbooks — Ansible Community Documentation). Having a small section in “Ansible playbooks” (Ansible playbooks — Ansible Community Documentation) that references the longer subsection for details is OK IMO, but I would keep more details from that page.

(For me, play argspec is an advanced topic, the intro page should only cover the absolute basics, with references to more.)

2 Likes