Skip to content

Latest commit

 

History

History
77 lines (54 loc) · 2.86 KB

DOCUMENTING.md

File metadata and controls

77 lines (54 loc) · 2.86 KB
Raw

Contributing to the Exoscale Terraform Provider documentation

Your contributions to the Exoscale Terraform Provider documentation are all welcome.

In fact, thoroughly documenting new features or behaviors is mandatory for all PRs introducing them.

In order to maintain the documentation uniform, we ask that you follow the following conventions.

Arguments and attributes

  • All resources, data-sources, attributes and arguments names must be highlighted; example given: exoscale_compute_instance

  • All resources, data-sources, attributes and arguments (example/default) values must be highlighted; example given: standard.medium

  • When applicable, resource and ad-hoc data-source must be hyperlinked one to another; example given (for the exoscale_compute_instance resource): Corresponding data sources: exoscale_compute_instance.

  • All arguments - parameters passed to resources/data-source - must be documented:

    • (Required) arguments are always first; their block must be separated from optional ones (next) by a blank line

    • Then comes optional arguments; default value must always be mentioned; example given: (default: standard.medium)

    • When not obvious, mention the argument type too, followed by its default if optional; example given: (boolean; default: true)

    • (Deprecated) arguments are always last; their block must be separated from optional ones (above) by a blank line

    • Within each block (required, optional, deprecated), arguments must be ordered by alphabetical order.

    • With the exception of well-known arguments, which must always come first, in the following order:

      • zone
      • id
      • name
      • description

  • All attributes - values returned by resources/data-sources - must be documented:

    • (Deprecated) attributes are always last; their block must be separated from regular ones by a blank line

    • Within each block (regular, deprecated), attributes must be ordered by alphabetical order.

    • With the exception of well-known attributes, which must always come first, in the following order:

      • zone
      • id
      • name
      • description

Usage and use-case examples

Resources or data-sources Usage examples must be kept as simple as possible, demonstrating the use of arguments and resources independently from other resources/data-sources.

Use case examples - mixing different resources and data-sources to achieve a well-identified purpose - must be stored in the examples directory (where they may be hyperlinked from each individual resource/data-source docs pages); example given: Please refer to the examples directory for complete configuration examples.

Locale and encoding

Please use en_US.UTF-8 locale/encoding, in particular in respect with spell-checking.