Docs.folio.org content standards

When developing content, the topic must be structured in a manner consistent with the current documentation.  Topics that describe app functionality must include an introductory statement, a list of related permissions, and definitions that are relevant to the particular app.

Within a topic, the description of creating, for example, a "new" invoice/course/etc. comes before a description of "searching and filtering" for relevant content.  It is then followed by a description of viewing displayed information. 

Topic contents are also structured in relation to how they appear in the user interface.  Within each topic, it is necessary to notice when subsections are used vs. bulleted lists of field descriptions.  It is important to use current topics as a model for any future topics written.

The style guide selected for the project is the Google Developer Style Guide.  Note that the style guide calls for the use of simple, direct language to enable non-native English speakers to be able to understand the content.  The use of simple language also paves the way for future localization efforts.  Accessibility guidelines should also be considered carefully.

Beyond these considerations, the guide recommends overall best practices, including avoiding multiple levels of nested bullets/numbered steps or the use of passive tense.  Attention must be paid to style and grammar, including but not limited to consistent capitalization, bolding conventions, and order of directions for numbered procedures.  Given that the documentation has multiple authors, each with their own general style and approach, it is critical to re-work materials until a consistent voice is achieved.

Consistent terminology is also key to the usability of the FOLIO documentation. It is important that the terminology used in the user interface is accurately reflected in the documentation to create a seamless user experience.