Wiki/Operation/Manual_of_Style.md

26 lines
1.9 KiB
Markdown
Raw Permalink Normal View History

This is intended to give contributors a baseline for editing.
# Proper naming
Services on this network are properly titled in the below format. This should always be used the first time a service is referenced.
```
AniNIX/{ServiceName}[ | {Area}]
```
# Grammar
Grammar is a writer's toolbox. You can't build good sentences without knowing how to use your tools. Since a wiki article should be as clear as possible for all those reading it, editors should keep their edits as grammatically correct as is possible, in order to ensure clear communication of the information being provided. Follow proper English language standards.
# Writing Style
_Be concise._ Professionals are already taxed for time to maximize their utility; they need clear, direct language to understand what needs to be done. In this simplicity of purpose beauty is found, not in flowerly, lengthy prose.
_Contain your scope._ Avoid letting your scope creep beyond what is meaningful to the task at hand; documentation should be like the tools being described: narrowly defined, and deeply explored.
_Be impersonal._ Avoid making statements that indicate personal preference as an authority; rather, indicate why what's being done is the best available.
_Use present tense._ These services, enttitles and policies are active, living, and fluid -- because they're changing now, we use present tense to describe current state.
# Images
We generally will not use images in these projects -- very little is represented better as images than as code snippets for a deep infrastructure system like the AniNIX. If you do need images, generally speaking it is best to contact an AniNIX admin to distribute the image via some CDN outside of Foundation, rather than committing it directly. Repos that are mirrored out to GitHub may be an exception.
# Useful Snippets
See [the upstream syntax notes](https://daringfireball.net/projects/markdown/syntax) for examples.