Documentation/Toolkit/Findability review
< Documentation | Toolkit
This page provides a review checklist you can use to help ensure that readers can find docs by searching and browsing.
Review checklist
[edit]If a page serves a special purpose or covers a niche topic, it may be okay if it has very few incoming links. However, if the page contains information relevant for a wide audience, look for the following to try to improve the content's findability:
- Clear and concise page title: The title should be descriptive and specific. This helps searchers decide whether to click links to the page. Also, on-wiki search sends users directly to a page if it has the same title as their search query, so the more the page title aligns with user's language, the more likely they are to find it. Example: "Accessing Instances on Cloud VPS" is a more descriptive and specific page title than "Instances".
- Short introduction: Include a short introduction as the first text on the page following the title, before the first heading. This should briefly introduce the purpose of the page, its audience, and topic. Intro section content often appears as a snippet in search results, so it help searchers assess the relevance of a page for their need.
- Shallow page nesting (subpaging): Avoid creating subpages deeper than 3 levels. This can make it harder to find pages by browsing. Also, on-wiki search results display the entire page path, so more shallow subpaging makes it easier to read page titles in search results.
- Templates: Check for templates like {{Historical}} or {{Archive}}. Depending on the wiki's search configuration, these templates can cause a page to be ranked lower in search results. If the page should be historical or archived, this is a good thing.
- Navigation menus: Is the page part of a collection of pages that use a navigation menu? If so, is the page included in that menu? Should it be?
- Cross-references to and from code: if this is a page for a specific product or technology: are there links in both directions between code and on-wiki docs? Specifically check for the following:
- Does the wiki landing page for the product/technology include links to the relevant code repositories and issues trackers?
- Is there a README or documentation stored in the root directory that includes a link to the on-wiki documentation?
- If the page relates to a tool or component that has a web UI: are there links in the tool/web UI to the on-wiki documentation?
- Categories: Is this page part of a thematic area in which other pages use Categories? If so, check the definition of the Category and consider adding it to your page.
- Links from related, popular pages: Use Special:WhatLinksHere to identify incoming links. If there are none: are there pages that should link to this page? On-wiki search sorts suggestions by the number of incoming links, so pages that have no incoming links may appear lower in results lists.
- Consider which other pages users might encounter when trying to find the information on your page. Try searching on the wiki for keywords related to your page, and explore the pages at the top of the search results.
- When you find related pages, consider how the reader of that page may benefit from your page. Under what conditions would they need the information on your page?
- If you find a more prominent and well-known page that could be a better home for your content, consider consolidating your page's content into the more popular page, and adding a redirect or cross-reference. This process helps consolidate useful and relevant information into already heavily-used pages, and reduce the number of pages users must consult to get valuable information.
Look for meaningful places to add links to your page from related pages. Avoid creating long lists of links in See Also sections; this makes it more difficult for readers to understand the relevance of each link in the list.