Our writing guidelines

Our publications and documentation are representative works of Project Elara, and we want to make sure it is top-quality writing. If you would like to contribute to them, please follow these guidelines!

AI use policy¶

Do not use generative AI for generating large chunks of text. We cannot guarantee the accuracy or quality of AI-generated writing. If English is not your first language and you want to use AI to help you write, please remember that we are there to help you, and you don’t have to write perfectly. The use of spellcheckers/grammar checkers with optional AI features (e.g. LanguageTool) and generative AI for machine translation is allowed, as long as the AI is only used for a rough draft and the translation is then manually proofread and edited, preferably by a native speaker.

Writing style¶

Writing the Handbook should follow the same general style as standard scientific/technical writing:

• Make sure that your writing is structured into logical sections, which are distinguished by headings.

• Do not use “I”, “my”, “mine” in writing.

• Do not write overly long sentences; split a long sentence into several shorter sentence whenever appropriate. Likewise, do not write overly long paragraphs; split a paragraph into several whenever appropriate.

• Use proper capitalization, tense, punctuation, and grammar. The use of a basic spelling/grammar checker is strongly recommended; spell-checking and grammar-checking plugins are available for most text editors.

• Do not write from a Eurocentric (Western-style) viewpoint, or assume the reader has a particular cultural background. Ensure your writing is accessible to a wide audience. Use gender-neutral pronouns by default, and be culturally-sensitive and considerate of others. If you are unsure about your writing, please consult the Alex word checker or ask a member of our team.

Formatting¶

Writing should be formatted using the Markdown syntax, including appropriate use of code blocks, tables, and images. If you are unfamiliar with Markdown, please take ~10 minutes to complete the Markdown tutorial. Code blocks should have the correct language tag to ensure syntax highlighting displays correctly. Equations should be written in LaTeX (see this tutorial if you are unfamiliar with it).

Attribution policy¶

If you use or refer to anything that you did not create, please attribute the author(s) of the work. Online images may be used under Fair Use, but please still add a link to the source wherever you can.

Editorial accuracy and transparency policy¶

We aim to follow Wikipedia-style guidelines to ensure transparency and accuracy of our content:

• Any content that is a first draft, incomplete, or needs editing should be marked as such with a clear notice (and in the case of our Handbook, a MyST admonition)

• Any page that contains missing content should be flagged as incomplete at the top of the page

• Any page that has linked issues on Codeberg will be flagged as such at the top of the page

• Any section of any page that lacks due citations should be flagged as such; in addition, pages that generally lack citations

Other information¶

Please let our team know if you have any questions or concerns. And most importantly — enjoy writing!