Help:Editing
You shouldn't need to think too hard before editing this wiki.
If you see something that needs fixing then go ahead and fix it.
Below you can find guidelines to help you if you are making more complex edits or if you are considering creating a new page.
Before you start
Check the official documentation before adding a new page
There is official Ubuntu documentation maintained by dedicated engineering teams.
If you want to create a technical guide, check if it has already been published in the documentation.
When you don't think your idea "fits" in the official documentation, or if you are unsure, then add it to the wiki.
Search the wiki for similar pages
Someone may already have created a similar page.
Check if one exists using the wiki's search function.
If you find a page but think it can be improved, then start editing.
Editing pages
On most pages, there is an option to edit and edit source.
The first option is a visual editor that works similarly to word processing software like Word or Google docs. It works really well for most edits.
The second option is a source editor and requires you to use a special wikitext markup. This might seem complicated but there are several features that make it less difficult:
- Shortcuts: highlighting a word and clicking ctrl+b makes it bold by adding the markup for you
- Toolbar: you can use buttons for a variety of actions, including adding links and code
Even if you primarily use the visual editor, it can be helpful to switch the source editor if you need to troubleshoot rendering issues. You can switch back-and-forth between the editing modes whenever you want.
Creating pages
New users don't get page creation rights immediately
Creating pages follows the classic wiki model, where you can either:
- Create a link to a page that you want, but doesn't yet exist, and then follow the link to create the page
- Search for the page that you want and follow the prompt to create the page if it doesn't exist
There are good reasons for this approach:
- The requirement to search helps reduce the likelihood of pages being duplicated
- The incentive to link to new pages helps prevent "orphan" pages that are less likely to be found
When creating a page, keep the titles simple and descriptive.
Title casing
Avoid CamelCase titles.
If what you are referring to is known in CamelCase form, such as LibreOffice or GitHub, then using that title is OK.
There is no reason to use RemotelyDeployingUbuntuToServers instead of its Sentence case form 'Remotely deploying Ubuntu to servers'.
If you are migrating a page from the old wiki.ubuntu.com that used CamelCase but no longer needs it:
- Create the migrated page with a Sentence case title.
- Create another page with the CamelCase title that redirects to the migrated page.
General guidelines
The quality of the wiki depends on the community working together to improve existing content.
If a new page is lacking quality, it will be improved over time by the community.
Each contributor has a role in making this process as smooth and efficient as possible.
Avoid complex edits
You might be tempted to make wholesale changes to a page but it is best to divide your work into chunks.
For example, if you want to update a terminal command, but also find typos in the page, and also think that an introduction could be added, you should avoid combining these changes into a single edit.
In this case, you should instead make three separate edits. You will still achieve your goals, but the changes are more organized and easier for others to follow.
Imagine if someone find that your edit to the terminal command is wrong. It is far easier to address that issue if you have made a single edit that can be easily identified.
Write descriptive commit messages
If you avoid complex edits, it should be easier to write clear and descriptive commit messages.
For example:
- Good: fixed outdated terminal command for logging data
- Bad: various fixes to improve page
Monitor changes in the wiki
If you are an expert on a topic or a regular user of specific pages, you can add them to your watchlist.
You can then access them in Special:Watchlist and receive notifications when changes are made.
If you want to check for the latest updates across the wiki, review Special:RecentChanges.
Track quality issues
The quality control category is used to track pages that have been marked for attention.
Some of the reasons include:
- Page is a stub
- Page duplicates official documentation
- Page is the subject of an active discussion
Use categories
To help group the page with similar content, add a category at the end of the source:
[[Category:Desktop]]
Diataxis categories can also be useful to indicate whether the content is a how-to, tutorial, explanation, or reference:
[[Category:Desktop]] [[Category:Tutorial]]
This can also help subsequent editors improve the page by identifying if it combines multiple content types that could be better split into dedicated pages. For example, a page that includes an API reference in addition to a getting started tutorial should probably be split into two distinct pages: a reference page and a tutorial page.
Use discussions
If you are intending to make a major edit on a page, you should start a thread in the associated discussion page.
Others users may be able to offer advice or support. They may also have objections worth considering.
This helps prevent scenarios where you waste valuable time on edits that are later reverted by other editors.
I want to contribute but I don't know where to start
The wiki includes pages that can help you identify opportunities:
- Category:Quality control: Pages marked for quality issues
- Special:WantedPages: Pages that are linked to but don't exist yet
- Special:DeadendPages: Pages that don't link out to other pages
- Special:LonelyPages: Pages that no other pages link to
- Special:ShortPages: Pages that are tiny or stubs and could be expanded
You can improve the wiki by creating pages that people want, improving inter-linking, and expanding short or incomplete pages.