The Codeberg Documentation website by The Codeberg Documentation Contributors is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
It bundles third-party font software licensed under a different license. Please look at the LICENSE file for details.
Changes to the original versions of the article as well as its individual authors can be looked up in this article's commit history
Codeberg and the Codeberg Logo are trademarks of Codeberg e.V.
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 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.
In an ideal world, the reviewer is the person that must be in charge of enforcing the guidelines provided in the style guide.
This style guide is a starting point. Feel free to create an issue, open a Pull Request, and modify it according to the community's needs.
We intend to reach people from different knowledge backgrounds and life experiences. Therefore, we kindly ask you to follow these rules:
| Rule | What we recommend |
|---|---|
| Be as neutral as possible | Avoid using slang and colloquial expressions |
| Be as clear as possible | Avoid wordy sentences. Don't expect your readers to “guess” the intended meaning from context |
| Be as concise as possible | Keep your sentences short and prefer active over passive voice |
We are still at the beginning of our documentation journey. As of now, the style guide consists of three main components:
Feel free to suggest any additional points and/or sections you deem necessary.
Follow these guidelines to organize the structure of your document:
$.root / an administrator, prepend the character #.Screenshots and other images can heavily improve the quality of an article without much effort.
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.
Before including screenshots, we highly recommend writing articles in text first.
Some parts of the Documentation do not comply with the current rules and recommendations yet.
Wikipedia's Manual of Style contains several good examples of alt text.
| Content type | What we recommend | Explanation |
|---|---|---|
| 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.:
By ordered lists, we mean numbered lists. Use ordered lists to describe procedures that involve multiple sequential steps, e.g.:
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.
Use curly quotes instead of straight quotes, e.g.:
| Do not write | Write |
|---|---|
| "That's an 'interesting' task" | “That's an ‘interesting’ task” |
| "We're 'happy' that you're here" | “We're ‘happy’ that you're here” |
Please follow the conventions below to ensure a consistent format of dates, times, and numbers.
Use the following format for dates in running text: dd MMMM yyyy, e.g. 9 March 2022.
Use the following “short” format for dates outside the running text: dd.mm.yyyy, e.g. 9.3.2022.
Do not use leading zeros in dates, e.g.:
| Do not write | Write |
|---|---|
| 09 March 2022 | 9 March 2022 |
| 09.03.2022 | 9.3.2022 |
Use the 24-hour system. Do not use the 12-hour system with a.m. and p.m.
Do not use leading zeros to indicate time. Write full hours with zero minutes.
| Do not write | Write |
|---|---|
| 6.20 p.m | 18.20 |
| 12 | 12.00 |
| 09.03.2022 | 9.3.2022 |
Write out the numbers zero to nine in letters.
Use digits for all numbers above 9.
Use a combination of digits and letters when you have numbers that involve millions, billions, etc.
| Do not write | Write |
|---|---|
| 0 to 9 | zero to nine |
| Twenty five pages | 25 pages |
| Twenty billion | 20 billion |
Write “email” in lowercase characters without a hyphen. Do not use any other variant such as “e-mail” or “E-mail”, etc.
Use hyphens with compound adjectives and adverbs before nouns to eliminate any possible ambiguities, e.g.:
| Do not write | Write |
|---|---|
| Self evaluating object | Self-evaluating object |
| Well formed XML documents | Well-formed XML documents |
| Low level programming language | Low-level programming language |
| High performance databases | High-performance databases |
| Impossible to type characters | Impossible-to-type characters |
Do not use hyphens for adjectives and adverbs ending in -ly, e.g.
| Do not write | Write |
|---|---|
| Fully-qualified domain name | Fully qualified domain name |
| Highly-scalable application | Highly scalable application |
| Dynamically-typed languages | Dynamically typed languages |
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.
Avoid the excessive use of hyperlinks and cross-references within your document to prevent readers from being distracted.
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.
Keep notes and warnings outside the body of your running text. Use admonition boxes, also known as callouts, to show said information.
The syntax is as follows:
{% admonition "type" "title [optional]" %}
Content
{% endadmonition %}
If no title is provided will the admonition box default to the type being used as title.
Note the gaps between the content and the start and end tag. These are required to allow markdown to be rendered.
The following admonition types are currently available:
Default type used should no type or an invalid one be provided. Should be used to give short and useful information to know about.
Can be used to provide short snippets of information.
Use to indicate possible issues and problems, or known pitfalls a user should look out for.
Can be used to give suggestions and hints to a user.
Use to show and answer a question the user may ask in this situation.
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):
| Content type | Recommended structure |
|---|---|
| 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. |
| Do not write | Write |
|---|---|
| You're not going nowhere | You're going nowhere |
| He didn't see nothing | He didn't see anything |
We use the standard American spelling conventions, i.e.:
| Do not write | Write |
|---|---|
| flavour; colour; labour | flavor; color; labor |
| analyse; organise; standardise | analyze; organize; standardize |
| catalogue; analogue, dialogue | catalog, analog, dialog |
| defence, licence | defense, license |
Hey there! 👋 Thank you for reading this article!
Is there something missing, or do you have an idea on how to improve the documentation? Do you want to write your own article?
You're invited to contribute to the Codeberg Documentation at its source code repository, for example, by adding a pull request or joining in on the discussion in the issue tracker.
For an introduction on contributing to Codeberg Documentation, please have a look at the Contributor FAQ.
© Codeberg Docs Contributors. See LICENSE