<aside> 💡 ‘Good’ documentation shouldn’t be subjective. A style guide is a list of technical writing rules and best practices.

</aside>

• Table of Contents

To ensure Aragon’s documentation has consistent quality and style, we have developed the following style guidelines which should be implemented every time we’re writing documentation.

For every feature merged, there should be documentation explaining what the feature is, why it was built, and how to use it.

Here’s a detailed guide as to what this means:

Development Process

This documentation should live within the docs folder of the repository the developer is working on (i.e. aragon/core, aragon/sdk, etc).

— To get a deeper dive on the documentation lifecycle from feature to Developer Portal, you can find more details here: ‣.

Types of documentation

The documentation needed will take 4 main forms:

• Reference Guide: The purpose is to allow devs to get a detailed account of what every function within our documentation does. Each function and contract should have:
  • a type account of every variable and parameter within it,
  • a description explaining what that function does,
  • and a code sample example on how to use it.
• Context Piece: Whether it is a use case article or a how-to tutorial, these Context Pieces allow readers to get a better grasp about why they’d want to use one function vs the other and how to implement it.
• Change log: For every new version, there should be a Change log detailing what has changed so that developers using older versions are kept up-to-date.
• Complimentary: Acting as supplementary information, Complimentary documentation are things that are not necessarily explanatory in nature, but which act as support for better product scalability like a Best Practices section or a Support page.

Style Guide

There are three sections in this guide:

• Writing Style, our high-level approach to writing technical tutorials.
• Structure, an explanation of our layout and content.