---
# System prepended metadata

title: markup language options for Docs
tags: [Documentation]

---

# markup language options for Docs

###### tags: `Documentation`

We have the ability to switch some smaller Ansible projects (like the upcoming sdk) to use asciidoc, which is what the downstream docs projects and customer portal use for customer docs.  Whether we choose to do this depends on:
* Impact on docs contributors (will we lose or gain contributions based on this change).
* Overarching Community strategy - do we want to formalize all ansible projects on the same markup language (likely RST) so we are consistant and a contributor doesn't have to go find out what language is used when they want to make a 'drive-by' contribution to the docs of one or more Ansible projects.

## Polling the community
To come to a decision on the first bullet list, we could poll the potential contributors with a question something like the following:

**Does the docs markup language type impact your ability to contribute to docs?**
Background - ansible/ansible uses RST as do many of the other projects in the Ansible umbrella, but not all. Some us .md, others may choose asciidoc, etc.  As a docs contributor, please vote:

1. Doesn't matter. If I find a docs problem, I'll fix it. 
1. <xxx> markup only or I'll never contribute
1. Consistency is important. Choose one markup for all ansible projects and stick to it so I don't have to learn multiple markup options just to fix a docs problem.
    
Once we decide on the wording, we can create a `community-topic` to get votes from the community.  That said, we do have three communities here for potential docs contributions:
* ansible community aka external volunteers
* Red Hat internal developers
* Red Hat CCS writers
    
We can choose separate polls for all three, or combine them in one vote.