This document outlines general guidelines for writing documentation at ProVal.
↩️ Standards for specific languages can be found in their respective language subfolder. Be sure to read this document before diving into other languages!
Composition in professional writing refers to the arrangement and organization of ideas, information, and arguments into a clear, coherent, and effective written work. It involves the careful selection and ordering of words, sentences, paragraphs, and other elements to convey a specific message or achieve a desired outcome. Professional writing compositions can take many forms, including reports, memos, emails, proposals, and more, and they often require attention to tone, style, and audience. The goal of composition in professional writing is to communicate information effectively and persuasively to the intended reader or audience.
🤖 Generated by ChatGPT
The tone of our documentation is expected to be objective. Expressing emotion, opinion, or using slang in documentation is not acceptable. It should clearly express the intention of the work and not deviate into subjective matters or take on an informal cadence.
The style of our documentation should be academic. Be as informative as possible with an easily parsable structure. Concepts should be properly ordered and described so that the reader can understand the work as quickly as possible without sacrificing important information.
The audience for our documentation is generally other IT professionals. This means that a level of complexity is appropriate. However, diving into details on programming concepts would be going too far and inappropriate. We should be writing a document that can explain how the reader can utilize our work and what steps should to be taken before, during, and after that use.
Readability means ensuring that punctuation, capitalization, and grammar are correct. All documentation will be written in the English language with the United States subculture. This is to ensure that our documentation is both legible, professional, and standardized.
Sensitive information about ProVal or any entity should never be present in documentation. We should also note any security risks associated with utilizing our work when applicable, and how best to mitigate these risks.