###### tags: `Documentation` # Portable source content Documentation is an engineering function. Projects make their own decisions about using RST, MD, or ADOC. User documentation should be minimal in content and in form. It should be concise to more quickly convey meaning. It should also be simple enough that contributing requires only the English language and a text editor. As a design principle for project documentation, portability achieves the following: - Reduces the barrier to entry for contributions. - Avoids complexity for longer-term maintainability that prevents content degradation. - Makes content simple, readable, and easy to navigate more inclusive of users with assistive technology. - Ensures reliable conversion. If content is independent of the format then it is easier to author in RST and publish in ADOC or vice versa, as an example. About conversion. It should never be an end goal for content, only a mechanism that accelerates collaboration. ## Making docs portable The goal of portability is to have a consistent authoring experience across multiple lightweight markup formats. Lightweight markup should be as close to authoring in plain text as possible. ### Cross-references Sphinx is awesome but interlinking is not something other tools do well. While it is possible to convert RST `ref` to ADOC or MD `xref` the point is more about using a well-formed, consistent ids and anchors as well as using `ref` sensibly and sparingly. Main for the purposes of SEO, the ideal id is composed of lowercase whole words, avoiding prepositions and delimited by hyphens. For instance `getting-started-controller` is better than `ag_start`. It's also a good idea to make the id match the heading as closely as possible. That helps you find where to make edits in the doc source. ### Other best practices - Externalize code blocks to native file type and use include directives. This avoids embedding yaml in rst for example. You can then do things like lint yaml files separately or validate classes. - Ensure the paths for all include directives is relative to the referencing file. - Use [Semantic line breaks](https://sembr.org/) to make editing and PR reviews more comfortable but also to prevent text reflows. - Use `.. list-table::` in RST for simplicity and accessibility. - Avoid asciidoc callouts. It's asciidoc-specific and usually results in embedding asciidoc fragments in code blocks. This should only be done for canonical examples of code that is embedded in an asciidoc file. Code comments are much preferable to callouts. - Deeply nested headings. - Naming variables for project and component. Avoid these in headings. ### Diataxis At the point where there are defined personas for the Ansible community we can map personas to journeys. Then we can have a complete view of the content needs to support user paths. The [Diátaxis framework](https://diataxis.fr/) aims to solve the problem of structure in technical documentation and identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. The intersection between Diataxis and portable source content is information mapping. A documentation set should consist of different types of content, roughly procedural, conceptual, and reference. Engineering teams naturally write more reference content, enumerating programmatic options and their expected behaviour. Reference content should ideally be generated from source code, which is where engineers work. It's not reasonable to have any sort of expectations of content portability there. However, focusing user documentation on the Diataxis modes of tutorials, how-to guides, and explanation furthers the goal of achieving a consistent authoring experience. It's also worth noting at this point that we should never try to impose any sort of Diataxis template on project docs. Templates are a pitfall and go against the very notion of portability. They are often too rigid and focus more on the structure than the content. ### Community analysis Let's get community buy-in and discuss this initiave with the DaWGs. It would be interesting to do more comparison of lightweight markup and come to an agreement on a set of universal best practices. https://hyperpolyglot.org/lightweight-markup ### Contributor guidelines As an outcome of the community analysis it would be good to define a set of rules and best practices for avoiding complexity in doc content. Revise https://docs.ansible.com/ansible/latest/dev_guide/style_guide/index.html# to incorporate the rules and best practices. ### Lint tooling and rules Investigate custom rules with https://github.com/errata-ai/vale Perhaps we can extend Ansible Lint to help enforce the rules we create. One of the objectives of this sort of linting is also to do qualitative analysis and build a picture of the complexity of the entire Ansible doc set. We can then drive Hackathons and other community events.