Dead link about page titles

Summary

• Page properties (5 modified, 0 added, 0 removed)

Details

Page properties

Title

...	...	@@ -1,0 +1,1 @@
	1	+Page Titles and Page Names

Parent

...	...	@@ -1,0 +1,1 @@
	1	+Community.DocGuide.DocumentationStyle.WebHome

Author

...	...	@@ -1,1 +1,1 @@
1		-XWiki.XWikiGuest
	1	+xwiki:XWiki.gabrielc

Default language

...	...	@@ -1,0 +1,1 @@
	1	+en

Content

...	...	@@ -1,0 +1,50 @@
	1	+{{box cssClass="floatinginfobox" title="**Contents**"}}
	2	+{{toc/}}
	3	+{{/box}}
	4	+
	5	+Whenever you create or edit a documentation page, it is important to follow a consistent style. The rules below provide guidance on structure and terminology for [[page names and titles>>xwiki:documentation.xs.user.base.page.edit-page.titles-names.WebHome]].
	6	+
	7	+
	8	+* Page Titles should follow closely the [[Page Name>>||anchor="HPageNames"]].
	9	+* All Page Titles and [[Page Names>>||anchor="HPageNames"]] must be meaningful and understandable out of context, such that readers should be able to understand what a page is about. This is important because pages are often accessed through search results, bookmarks, links, where context is missing.
	10	+* Page Titles and Names must not include the type of the page ("How to", "Explanation", etc.). These are considered reserved terms, since the page type is already conveyed though the [[content>>||anchor="HDiataxisReflectedinPageTitleandPageContent"]], [[structure>>Community.DocGuide.PageStructure.WebHome]], [[badge>>xwiki:documentation.extensions.user.documentation.create-documentation-page.page-structure.WebHome]], context. Including them in titles or names creates redundancy.
	11	+
	12	+== Diataxis Reflected in Page Title and Page Content ==
	13	+
	14	+[[Diataxis>>https://diataxis.fr/]] is reflected not only in the way the [[documentation is organized>>dev:Community.DocGuide]], but also in its style. The type of the documentation page influences the style rules, make sure that page titles and content follow the conventions for that type.
	15	+
	16	+(% class="table-bordered" style="margin-left:auto; margin-right:auto; width:1070px" summary="Diataxis in style" %)
	17	+|= |=How-to|=Tutorial|=(% style="width: 182px;" %)Reference|=(% style="width: 283px;" %)Explanation
	18	+|**Page titles**|(((
	19	+Titles must start with a verb (e.g. "Select", "Apply", "Set", etc)
	20	+)))|(((
	21	+* Titles must start with a verb.
	22	+* Be more specific, since tutorials are How-to's applied to a concrete example, the title is also more specific.
	23	+)))|(% style="width:182px" %)(((
	24	+* Titles must not start with a verb.
	25	+* The title must clearly indicate that the page covers the topic extensively.
	26	+)))|(% style="width:283px" %)(((
	27	+* Titles must not start with a verb.
	28	+* Use a phrase that represents the subject of the explanation (answering “why”).
	29	+)))
	30	+|**Page content**|(((
	31	+* Any step in a How-to must start with a verb and each step is an item of a [[numbered list>>xwiki:Documentation.UserGuide.Features.XWikiSyntax.WebHome]].
	32	+* Don't add extra explanations, instead use the [[FAQ section>>Community.DocGuide.PageStructure.WebHome]] to formulate questions and answers from the reader's POV.
	33	+)))|Any step in a Tutorial must start with a verb and each step is an item of a [[numbered list>>xwiki:Documentation.UserGuide.Features.XWikiSyntax.WebHome]]. Short example sentences at any step are allowed to illustrate what exactly needs to be done.|(% style="width:182px" %)(((
	34	+* Reference pages must contain tables as a best practice because they present concise information and avoid verbosity.
	35	+* For API reference pages, tables may be replaced by the [[code macro>>||anchor="HMacros"]], and usage examples should be provided as a best practice.
	36	+)))|Explanations-type pages are describing concepts, limitations, consequences, most of the time answering the question "Why".
	37	+|**Examples**|"Edit a Page", "Build an Application" (and not "Editing a Page", "Building an Application"). More examples on [[How-tos for Users>>xwiki:documentation.xs.user.howto.WebHome||anchor="HWhatareyoulookingfor3F"]].|"Build a FAQ Application".|(% style="width:182px" %)"All Wiki Pages", "Common Edit Actions", "Realtime Edit Actions". More examples on [[References for Users>>xwiki:documentation.xs.user.reference.WebHome||anchor="HWhatareyoulookingfor3F"]].|(% style="width:283px" %)"Simple and Advanced User", "Conflict Resolution". More examples on [[Explanations for Users>>xwiki:documentation.xs.user.explanation.WebHome||anchor="HWhatareyoulookingfor3F"]].
	38	+
	39	+* When you want to add a disambiguation to a page title, you can do so by adding a qualifying phrase in parentheses `()` It's not necessary to add it to the page name. (For example:
	40	+[[All the Pages on the Wiki (for Administrators)>>xwiki:documentation.xs.admin.base.page.all-wiki-pages.WebHome]], [[All the Pages on the Wiki (for Users)>>xwiki:documentation.xs.user.base.page.view-all-pages.all-wiki-pages.WebHome]], [[Use Colibri ColorTheme Variables (Deprecated)>>xwiki:documentation.xs.dev.flamingo-skin.style-variables.use-colibri-colortheme-variables.WebHome]]).
	41	+
	42	+== Page Names ==
	43	+
	44	+Any new page created on [[xwiki.org>>xwiki:Main.WebHome]], as well as any [[extension>>extensions:Main.WebHome]] page that has been completely refactored into the [[new location of Documentation>>xwiki:documentation.WebHome]] pages (where the only remaining content is a link to the extension documentation and the extension is renamed), must follow the rules for naming:
	45	+
	46	+* Use the [[naming strategy for kebab-case>>extensions:Extension.Model.Validation.Default.WebHome]] when naming pages.
	47	+* Until when XWiki.org is upgraded to {{version since="18.1.0"}}Remove stop words manually. Do not include common stop words such as "a", "the", "on", "when", "while" etc. See [[full list of stop words>>extensions:Extension.Model.Validation.Default.WebHome||anchor="HKebab-caseStrategy"]].{{/version}}
	48	+* Page names should follow page titles as closely as possible while still respecting the rules above.
	49	+* Avoid repetition in URL paths.
	50	+** Do not repeat the same word (or variations of it) in both parent and child page names. Instead, rely on the parent path to provide context. For example, {{code language="none"}}../wiki-editor-toolbar/wiki-editor-toolbar-support{{/code}} repeats "wiki-editor-toolbar", so the correct name is {{code language="none"}}../wiki-editor-toolbar/support{{/code}}.