# PROPOSAL: 'description' parameter **URL:** \ **Category:** Ansible Project\ **Created:** [October 1, 2014, 6:57am UTC](https://forum.ansible.com/t/proposal-description-parameter/16391 "2014-10-01T06:57:15Z")\ **Posts on this page:** 6\ **Page:** 1
**Author:** ![shirou](https://avatars.discourse-cdn.com/v4/letter/s/ea5d25/32.png) [@shirou](https://forum.ansible.com/u/shirou)\ **Post date:** [October 1, 2014, 6:57am UTC](https://forum.ansible.com/t/proposal-description-parameter/16391/1 "2014-10-01T06:57:15Z")
Hi list, I'd like to open a discussion about "description" parameter. Ansible does nothing about on it. It just describing what is it. I know YAML can have a comment and name is good to know what this task do. But comment is not structured and name can not be long because handlers use it. If ansible defines "description", some documentation tool like Sphinx [1] can read it and produces a good document. ---
**Author:** ![Michael\_DeHaan1](https://avatars.discourse-cdn.com/v4/letter/m/5e9695/32.png) [@Michael\_DeHaan1](https://forum.ansible.com/u/Michael_DeHaan1)\ **Post date:** [October 1, 2014, 11:59am UTC](https://forum.ansible.com/t/proposal-description-parameter/16391/2 "2014-10-01T11:59:06Z")
Typically “name” has been used to provide a user readable comment and we haven’t added code for ecosystem things that aren’t part of the ansible project. One thing of caution to mention is that, currently, on the include this would set a variable called “description”. My gut feeling is some playbook “output” tool would have to exist to want to do that first. ---
**Author:** ![shirou](https://avatars.discourse-cdn.com/v4/letter/s/ea5d25/32.png) [@shirou](https://forum.ansible.com/u/shirou)\ **Post date:** [October 1, 2014, 1:37pm UTC](https://forum.ansible.com/t/proposal-description-parameter/16391/3 "2014-10-01T13:37:54Z")
Thank you for the comment. 'name' is always printed when you play. If name is long, the output becomes too verbose. I mentioned the Sphinx in the previous mail, but we can implements an ansible command which can output description. When many people write playbooks for a long time, it is easy to lost the purpose and/or the reason of tasks/includes. I think some documentation tool which can integrated to the playbook is needed for the long-term DevOps. > One thing of caution to mention is that, currently, on the include this would set a variable called "description". I want to add description not only a playbook but also tasks or includes which can not define variables. > My gut feeling is some playbook "output" tool would have to exist to want to do that first. It could be. But it will bring complexity. Regards, WAKAYAMA Shirou ---
**Author:** ![Mark3](https://avatars.discourse-cdn.com/v4/letter/m/ecb155/32.png) [@Mark3](https://forum.ansible.com/u/Mark3)\ **Post date:** [October 2, 2014, 7:52am UTC](https://forum.ansible.com/t/proposal-description-parameter/16391/4 "2014-10-02T07:52:08Z")
Why would the use of the ‘#’ be not desirable? Ofcourse if you want to print the comments this won’t work but I can hardly imagine you want all that output on your screen. ---
**Author:** ![Michael\_DeHaan1](https://avatars.discourse-cdn.com/v4/letter/m/5e9695/32.png) [@Michael\_DeHaan1](https://forum.ansible.com/u/Michael_DeHaan1)\ **Post date:** [October 2, 2014, 8:50pm UTC](https://forum.ansible.com/t/proposal-description-parameter/16391/5 "2014-10-02T20:50:01Z")
Right, I think I’m leaning on “#” for YAML comments. The only disadvantage is if you had something “reading” the YAML to generate it, that would be harder, but it would have to understand playbook includes and task includes and role dependencies, to get it right. That might be difficult. We’ve just begun a bit of a refactoring effort to make much of this easier - to where a generator could easily step through tasks and walk them, but … yeah, the idea of a documentation tool for documenting playbooks seems to be a little strange to me, as I feel playbooks are that documentation. Having a structured “description” really doesn’t hurt much though, it’s innocuous. ---
**Author:** ![shirou](https://avatars.discourse-cdn.com/v4/letter/s/ea5d25/32.png) [@shirou](https://forum.ansible.com/u/shirou)\ **Post date:** [October 3, 2014, 8:32am UTC](https://forum.ansible.com/t/proposal-description-parameter/16391/6 "2014-10-03T08:32:55Z")
Thank you for your feedbacks. I agree playbooks are the documentation and YAML comments are enough for just reading some playbooks. I think playbooks are "source codes" and tasks are "functions". My description proposal is looks like "annotation" for a "function" or a "class". Annotations are formatted and used with comments all together. Please imagine there are hundreds of playbooks which someone wrote 3 years ago. Formatted description and a documentation tool can help you to understand at a glance what the playbook and the task is. A discussion of the structure under the description is still needed for good documentation, but 'description' parameter or something like that is a good start point, I think. Regards, WAKAYAMA Shirou