This style guide defines the writing and formatting standards used by the Ubuntu Documentation Team. Its purpose is to ensure that all documentation is consistent, accurate, and easy to understand for the widest possible audience.
Ubuntu documentation is written for users of all skill levels — from complete beginners installing Linux for the first time to experienced system administrators. When writing, always consider the least experienced reader in your intended audience. Technical accuracy matters, but so does accessibility.
The documentation is also read by people for whom English is not their first language, and is translated into many languages by the community. Simple, clear English makes translation easier and more accurate.
Active voice is clearer and more direct than passive voice.
Use "you" to address the reader. Avoid "the user" or impersonal constructions.
Documentation should be approachable and encouraging, especially for beginners. Avoid overly formal language, but also avoid slang, jargon, or humour that may not translate well. Never talk down to the reader.
Choose common words over technical jargon where possible. If a technical term is unavoidable, define it on first use.
Write in the present tense. Documentation describes what software does now, not what it did or will do.
Keep sentences short — aim for 20 words or fewer. Split complex instructions into separate steps or sentences. Long sentences are harder to translate and harder to follow.
Ubuntu documentation uses British English spelling (e.g., colour, licence, recognise). Set your editor's spell checker to British English.
Spell out numbers one through nine. Use numerals for 10 and above, and always use numerals for version numbers, file sizes, and technical values (e.g., "Ubuntu 22.04", "4 GB of RAM").
Consistent terminology is essential. Use the same term for the same thing throughout a document and across the documentation set.
Respect trademarks. Write Ubuntu, Canonical, GNOME, KDE with correct capitalisation. Do not add ™ or ® symbols in body text — they are only required in formal legal documents.
Every documentation page should have a clear, logical structure that allows readers to find information quickly.
Headings should be descriptive, not generic. A reader scanning headings should understand the topic of each section without reading the body text.
Use numbered lists for sequential procedures where the order matters. Each step should describe exactly one action. Avoid combining multiple actions in a single step.
Use bold for:
Use italics for:
Use callout boxes to draw attention to important information:
Note: This is an example of a note box.
Tip: This is an example of a tip box.
Warning: This is an example of a warning box. Use sparingly.
All command-line instructions, file paths, package names, configuration values, and code samples must be formatted in a monospace font using the appropriate markup.
Use inline code formatting for short commands, file names, package names, and values
mentioned within a sentence: install the openssh-server package; edit
/etc/hosts; set the value to true.
Use code blocks for multi-line commands or commands that the reader is expected to copy and run. Always include a comment or sentence before the block explaining what it does.
# Install the SSH server
sudo apt install openssh-server
# Start and enable the service
sudo systemctl enable --now ssh
Do not include the shell prompt character ($ or #) in code blocks
unless it is needed to distinguish user input from output. When showing both input and output,
use the prompt to distinguish them.
$ uname -r
6.5.0-28-generic
Include sudo in commands that require it. Do not assume the reader is running
as root. Explain what sudo does when it first appears in a document aimed at
beginners.
Link text should be descriptive. It must make sense out of context, as screen readers often list links independently of surrounding text.
External links (to sites outside the documentation) should open in the same tab unless there is a specific reason not to. Do not use link shorteners — always use the full URL. Verify that external links are still valid before publishing.
When referencing another section or page, use the section heading as the link text. Check cross-references whenever a document is restructured.
Screenshots can help users verify they are following instructions correctly. Use them judiciously — too many screenshots make documents hard to maintain and slow to load.
alt attribute describing the screenshot for accessibility.
Screenshots become outdated when the UI changes. Mark screenshots with the Ubuntu version
they were taken on (e.g., in the file name: software-updater-2204.png). Review
screenshots with each new LTS release.
All documentation produced by the Ubuntu Documentation Team is published under the DocteamLicense. By contributing to the documentation, you agree to release your contributions under this licence.
The licence allows anyone to freely copy, distribute, and modify the documentation, provided that they attribute the Ubuntu Documentation Team and release any modifications under the same terms.
Do not include content copied from other sources unless it is clearly compatible with the DocteamLicense. When in doubt, write original content or contact the team via DocteamCommunications.
Note: Questions about licensing can be directed to the documentation team via the mailing list or IRC channel. See DocteamCommunications for contact details.