The present style guide aims at streamlining the authoring process. We would like to maintain a consistent style to guarantee a pleasant reading experience. If you haven't done it already, please read the [Documentation Contributor FAQ](https://docs.codeberg.org/improving-codeberg/docs-contributor-faq/) before using this guide.
A style guide is meant to be used as a reference when there is a doubt about a style convention. Think of it as a set of recommendations to avoid time-consuming discussions about grammar, typography, and layout aspects.
It is not a novel that we expect you to read from A to Z. For instance, if you want to know how to format date and numbers, you can head immediately to the relevant section under [Dates, times, and numbers](#dates%2C-times%2C-and-numbers).
In an ideal world, the reviewer is the person that must be in charge of enforcing the guidelines provided in the style guide.
In our situation, screenshots generally help users find what they are looking for. They also use them to compare what _they_ are seeing with what the _article's author_ expects them to be seeing.
However, readers that cannot see images (e.g. users depending on screen reader software) should not be prevented from reading your article.
{% admonition "tip" %}
Before including screenshots, we highly recommend writing articles in text first.
{% endadmonition %}
- Use text to describe instructions (i.e. where does the reader need to click). Do not exclusively rely on visual cues (i.e. arrows, icons) in screenshots.
- When possible, use text to describe what you expect the reader to see after following an instruction or a set of instructions.
- When using images, always use an adequate amount of alt text.
{% admonition "warning" %}
Some parts of the Documentation do not comply with the current rules and recommendations yet.
{% endadmonition %}
{% admonition "info" %}
Wikipedia's Manual of Style contains [several good examples of alt text](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Accessibility/Alternative_text_for_images#Examples).
- Use sentence-style capitalization, i.e. capitalize only the first letter of the first word in the heading as well as words where capitalization is compulsory, such as proper nouns.
- Your headings must reflect the content of the text that follows.
| Conceptual | Noun or noun phrase | A conceptual text explains a concept, e.g. “Advantages of version control” |
| Procedural | Gerund | A procedural text describes a procedure or task, e.g. “Installing Git on you local machine” |
| Reference | Noun or noun phrase | A reference text provides information about different elements of a set, e.g. “Keyboard shortcuts” and “File formats” |
By unordered lists, we mean **bullet-style** lists. Use unordered lists when the sequence is irrelevant, e.g.:
- The print() function
- The input() function
- The len() function
By ordered lists, we mean **numbered** lists. Use ordered lists to describe procedures that involve multiple sequential steps, e.g.:
1. Type the URL into your browser's address bar
2. Press the Enter button
3. Go to the Login section and click on “Forgot Password”
Maintain a consistent punctuation style in lists. Decide whether you will use “complete sentences” or “sentence fragments” in your list items. Add a period (.) at the end of each list item if you choose to use complete sentences. Do not add a period at the end of each item if you are only using sentence fragments.
### Straight and curly quotes
Use curly quotes instead of straight quotes, e.g.:
If you write an excessively long article, your readers might get lost on the way. Break your article down in smaller articles for a better reading experience.
A standard paragraph consists of three to eight sentences. If a paragraph exceeds the maximum allowed number of sentences, reorganize the information to enhance readability.
Favor “self-contained information units” over interconnected information units. An information unit is called self-contained when it does not depend on other information units to convey meaning. Interconnected information units make an excessive use of pronouns and conjunctions such as “this”, “it”, “consequently”, “therefore”, etc.
Adopt one of the following approaches according to the typology of your content (cf. the difference between “conceptual”, “procedural”, and “reference” content under the section [Headings](#headings)):
| Conceptual | Use Definitions to introduce the reader to the subject matter before adding your explanations. Use paragraphs and unordered lists to explain the concepts. |
| Procedural | Provide a brief introduction to the procedure. Point out any prerequisites before you start describing the steps to follow. Use ordered lists for the different tasks |
| Reference | Provide a brief introduction in each section to help your readers decide whether they need this particular topic. Use subsections, tables and bullet-style lists to ensure easy access to information. |
