Documentation/Landing pages
Create a landing page that helps users navigate information about a specific product or technology. Provide basic context, organize links into meaningful groups, and include a communication process.
Examples[edit]
Description[edit]
A landing page serves as an entry point for documentation about a specific product or technology. Landing pages are primarily navigation-focused, but they also inform. They provide readers with just enough knowledge about a product/technology to decide if they should continue reading.
Page contents[edit]
Required[edit]
Descriptive title[edit]
Because landing pages help organize and contextualize other pages, the title of a landing page should be descriptive enough to make sense when viewed directly from a search engine.
What is the thing?[edit]
To provide context, a landing page should introduce the topic or theme of the page in the first section under the title. For example, a landing page for Toolforge should include a section that describes what Toolforge is, and its intended purpose or uses.
Main features of the thing[edit]
- Why would someone want to use this product or technology?
- What use cases does it address?
- What major functionality does it offer?
- Who is its intended audience or user base?
If a separate, more in-depth product overview or technology introduction exists, you can link to it and include this information there instead of on the landing page, but it should be easily accessible from the landing page. Remember, your goal is to enable readers to quickly determine if they should continue reading, or if this product/technology isn't right for them.
Constraints of the thing[edit]
- Why would someone NOT want to use this product or technology?
- What use cases does it not address?
- What major functionality might be expected but is not included?
- Who is NOT its intended audience or user base?
- Are there major technical or other prerequisites for using it, for example, knowledge of a certain programming language or a certain version of an operating system?
Link groupings[edit]
Format groups of links together in a way that is easy to navigate, such as Template:ContentGrid and Template:Colored box. Avoid organizing links with tables or headings.
Link groupings make it easier to scan and comprehend the content on a page. They create "meaningful, visually distinct content units that make sense in the context of the larger whole."[1] Organize links into groups that are meaningful for your reader. Usually, this means grouping links by user group or task. Avoid general categories like "Other resources".
Meaningful links only[edit]
Unlike encyclopedia articles, technical documents should only include links that are essential to understanding and using the product or technology. You don't need to limit links to a magical number like seven[2], but your landing page will be easier to use and maintain if you only include links to the most essential resources.
For every link that you intend to include on your landing page, consider the following:
- Does the reader absolutely need to know the information on that page right now? Or, will clicking the link only provide them with "nice to know" information? Are you linking to very specific information that would be hard to understand without additional context? To avoid information overload, use progressive disclosure[3]: keep your landing page content broad.
- Do multiple links guide users to pages that cover the same topics? Do any of the pages to which you're linking also link to each other? If so, pick only one link for that topic. Guide your reader to the best resource, not all the resources.
- Do you link to resources that should actually be read in sequential order? If so, link only to the first step on your landing page. You can link to the subsequent steps from the first page in the sequence. For example: only link to a "get started" page on your landing page, don't link to all the pages that may be involved in the "getting started" process.
Communication process[edit]
Include ways for people to ask questions, join a discussion, subscribe to updates, or contribute, whatever applies to the topic or theme.
Recommended[edit]
Image[edit]
If available, include an image relevant to the topic, such as a project logo. If there's no relevant image, don't include one. The image can be centered or aligned opposite the title (right-aligned in LTR languages).
<!-- Align opposite the title -->
[[File:Filename.png|alt=Alt text|{{dir|{{pagelang}}|left|right}}|120px]]
<!-- Align center -->
[[File:Filename.png|alt=Alt text|center|120px]]
Links to "Get Started" pages[edit]
Landing pages should include a grouping of links to help users get started using the product or technology. "Getting started" is the next step in the user's journey after the landing page has helped them confirm that this product or technology may be relevant for their goal.
Provide links to different types of content for getting started:
- For people who want to learn more by reading: Link to a conceptual overview that covers in more depth: the intended use of the product, core concepts a user should know to help them build their mental model.
- For people who want to just start doing: Link to a setup or quick start guide.
- For people who want to learn by practicing with examples: Links to tutorials or other hands-on learning tools.
Optional[edit]
[edit]
If a landing page has subpages, it should include a navigation element that allows readers to move between pages within the collection, such as a sidebar, navigation box, or set of tabs. You can also include a prefix search box.
Category metadata[edit]
If a use case exists for grouping together all product/technology landing pages in a given topic space, categorizing the landing pages is the best way to do that. Avoid creating large, exhaustive, manually-curated lists of products/technologies.
Content templates[edit]
| template | mediawiki.org | Meta-Wiki | Wikitech |
|---|---|---|---|
| mw:Template:ContentGrid | Available | Available | Available |
| mw:Template:Colored box | Available | Available | Available |
| mw:Template:Contribution | Available | Not available | Available |
| wikitech:Template:Portal list item | Not available | Not available | Available |
| mw:Template:Navbox | Available | Available | Not available |
| wikitech:Template:Prefix search | Not available | Not available | Available |
| mw:Template:pagelang | Available | Available | Available |
| meta:Template:Portal navigation | Not available | Available | Not available |