Style Guide - Revision history

Tobyvan: /* Additional guidelines for technical writing and editing */

2020-07-09T09:47:26Z

Additional guidelines for technical writing and editing

← Older revision		Revision as of 11:47, 9 July 2020
Line 12:		Line 12:
	===English Wikipedia Manual of Style===		===English Wikipedia Manual of Style===
	The [[wikipedia:Wikipedia:Manual_of_Style\|English Wikipedia's Manual of Style]] covers certain topics in detail (like punctuation) and summarizes the key points of others.		The [[wikipedia:Wikipedia:Manual_of_Style\|English Wikipedia's Manual of Style]] covers certain topics in detail (like punctuation) and summarizes the key points of others.
	===<span class="mw-headline" id="Additional_guidelines_for_technical_writing_and_editing">Additional guidelines for technical writing and editing</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span>[[/index.php?title=Style Guide&veaction=edit&section=1\|edit]]<span class="mw-editsection-divider"> \| </span>[[/index.php?title=Style Guide&action=edit&section=1\|edit source]]<span class="mw-editsection-bracket">]</span></span>===		===<span class="mw-headline" id="Additional_guidelines_for_technical_writing_and_editing">Additional guidelines for technical writing and editing</span>===
	It is important to follow clear standards and style guidelines for writing and editing documentation, especially when many individuals contribute to it with varying levels of skills and experience.		It is important to follow clear standards and style guidelines for writing and editing documentation, especially when many individuals contribute to it with varying levels of skills and experience.

Line 19:		Line 19:
	This page provides basic guidelines and tips to help get you started, as well as some specific information not covered in the Wikipedia Manual of Style.		This page provides basic guidelines and tips to help get you started, as well as some specific information not covered in the Wikipedia Manual of Style.

	~~This page provides basic guidelines and tips to help get you started, as well as some specific information not covered in the Wikipedia Manual of Style.~~		==Audience and content==
			===Writing for technical audiences===
	~~{{TOC\|align=right}}~~

	==Audience and content== ~~<!--T:13-->~~

	===Writing for technical audiences=== ~~<!--T:14-->~~

	Before you begin writing, it is important to think about the audience for your work.		Before you begin writing, it is important to think about the audience for your work.

	*Who do you imagine will be reading this technical documentation?		*Who do you imagine will be reading this technical documentation?


	*How familiar are they with the concepts you are presenting?		*How familiar are they with the concepts you are presenting?

Tobyvan: /* English Wikipedia Manual of Style */

2020-07-07T12:28:06Z

English Wikipedia Manual of Style

← Older revision		Revision as of 14:28, 7 July 2020
Line 2:		Line 2:
	==Overview==		==Overview==

	This page is a supplementary style guide for writing and editing technical documentation in ~~MediaWiki~~ and other technical spaces.		This page is a supplementary style guide for writing and editing technical documentation in [[The HILLSIDE\|theHILLSIDE]] and other technical spaces.


	It is intended to provide tips for writing clear, concise technical documentation in plain language, to highlight best practices and standards for a variety of technical documents used across projects, to share resources and knowledge about technical writing and editing in general.		It is intended to provide tips for writing clear, concise technical documentation in plain language, to highlight best practices and standards for a variety of technical documents used across projects, to share resources and knowledge about technical writing and editing in general.

	"Good" technical documentation makes it easier for individuals to make technical contributions ~~across Wikimedia~~ projects.		"Good" technical documentation makes it easier for individuals to make technical contributions projects.

	Whether you consider yourself a writer or not, your contributions are needed and appreciated.		Whether you consider yourself a writer or not, your contributions are needed and appreciated.

	===English Wikipedia Manual of Style===		===English Wikipedia Manual of Style===
	The [[~~<tvar\|1>https~~:~~//en.wikipedia.org/wiki/~~Wikipedia:Manual_of_Style~~</>~~\|English Wikipedia's Manual of ~~style~~]] covers certain topics in detail (like punctuation) and summarizes the key points of others.		The [[wikipedia:Wikipedia:Manual_of_Style\|English Wikipedia's Manual of Style]] covers certain topics in detail (like punctuation) and summarizes the key points of others.
	===<span class="mw-headline" id="Additional_guidelines_for_technical_writing_and_editing">Additional guidelines for technical writing and editing</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span>[[/index.php?title=Style Guide&veaction=edit&section=1\|edit]]<span class="mw-editsection-divider"> \| </span>[[/index.php?title=Style Guide&action=edit&section=1\|edit source]]<span class="mw-editsection-bracket">]</span></span>===		===<span class="mw-headline" id="Additional_guidelines_for_technical_writing_and_editing">Additional guidelines for technical writing and editing</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span>[[/index.php?title=Style Guide&veaction=edit&section=1\|edit]]<span class="mw-editsection-divider"> \| </span>[[/index.php?title=Style Guide&action=edit&section=1\|edit source]]<span class="mw-editsection-bracket">]</span></span>===
	It is important to follow clear standards and style guidelines for writing and editing documentation, especially when many individuals contribute to it with varying levels of skills and experience.		It is important to follow clear standards and style guidelines for writing and editing documentation, especially when many individuals contribute to it with varying levels of skills and experience.


	There are many style and usage rules for general writing – far too many to remember – and even more for technical writing.		There are many style and usage rules for general writing – far too many to remember – and even more for technical writing.
Line 21:		Line 19:
	This page provides basic guidelines and tips to help get you started, as well as some specific information not covered in the Wikipedia Manual of Style.		This page provides basic guidelines and tips to help get you started, as well as some specific information not covered in the Wikipedia Manual of Style.

			This page provides basic guidelines and tips to help get you started, as well as some specific information not covered in the Wikipedia Manual of Style.

	{{TOC\|align=right}}		{{TOC\|align=right}}

	== Audience and content == <!--T:13-->		==Audience and content== <!--T:13-->

	=== Writing for technical audiences === <!--T:14-->		===Writing for technical audiences=== <!--T:14-->

	Before you begin writing, it is important to think about the audience for your work.		Before you begin writing, it is important to think about the audience for your work.

	* Who do you imagine will be reading this technical documentation?		*Who do you imagine will be reading this technical documentation?


	* How familiar are they with the concepts you are presenting?		*How familiar are they with the concepts you are presenting?

	* What might they need to know in order to understand?		*What might they need to know in order to understand?

	Once you have an understanding of your audience, you will have a better sense of what you need to convey and how to convey it.		Once you have an understanding of your audience, you will have a better sense of what you need to convey and how to convey it.
Line 48:		Line 47:
	}}		}}

	=== Writing with a purpose ===		===Writing with a purpose===

	What purpose will your technical documentation serve? There are many reasons to write documentation.		What purpose will your technical documentation serve? There are many reasons to write documentation.
Line 54:		Line 53:
	It is helpful to know ''why'' you are writing and what your goal is before you begin.		It is helpful to know ''why'' you are writing and what your goal is before you begin.

	* Is it to teach someone, like a newcomer, about a process or concept?		*Is it to teach someone, like a newcomer, about a process or concept?
	* Is it to show someone how to follow a process?		*Is it to show someone how to follow a process?

	* Is it meant to provide background and context for a concept or process?		*Is it meant to provide background and context for a concept or process?

	* Is it a reference intended to provide information?		*Is it a reference intended to provide information?

	=== Writing within a context ===		===Writing within a context===

	When deciding what to write and how to frame it for your reader, it can help to define a context or occasion for your writing.		When deciding what to write and how to frame it for your reader, it can help to define a context or occasion for your writing.
Line 73:		Line 72:
	How could you best position your writing within the context of this community and its culture to create the most meaningful and useful technical documentation?		How could you best position your writing within the context of this community and its culture to create the most meaningful and useful technical documentation?

	=== User testing and feedback ===		===User testing and feedback===
	Create technical documentation to communicate ideas and concepts to a real audience of users.		Create technical documentation to communicate ideas and concepts to a real audience of users.
	Naturally, this audience should play a critical role in how the documentation is shaped and reshaped.		Naturally, this audience should play a critical role in how the documentation is shaped and reshaped.
Line 79:		Line 78:
	Take some time to answer the following questions:		Take some time to answer the following questions:

	* Does your documentation include a mechanism for feedback?		*Does your documentation include a mechanism for feedback?

	* Can you engage in timely conversations with the audience to make improvements?		*Can you engage in timely conversations with the audience to make improvements?

	=== Clarity and consistency ===		===Clarity and consistency===

	Your goal is to make accessing, reading, and creating technical documentation for MediaWiki/Wikimedia easier and more intuitive by promoting clarity and consistency throughout.		Your goal is to make accessing, reading, and creating technical documentation for MediaWiki/Wikimedia easier and more intuitive by promoting clarity and consistency throughout.
Line 91:		Line 90:
	This helps readers learn how to navigate information and makes it easier for contributors to understand how to edit and add new information.		This helps readers learn how to navigate information and makes it easier for contributors to understand how to edit and add new information.

	=== Deciding on a document type ===		===Deciding on a document type===
	{{see also\|Documentation/Technical documentation templates and suggestions}}		{{see also\|Documentation/Technical documentation templates and suggestions}}

Line 390:		Line 389:
	\|}		\|}

	=== Templates ===		===Templates===
	{{See also\|Documentation/Style guide/templates}}		{{See also\|Documentation/Style guide/templates}}

Line 411:		Line 410:
	*{{tl\|tracked}} for the related Phabricator task		*{{tl\|tracked}} for the related Phabricator task
	*{{tl\|wg\|RestOfVariableName}} for global variables		*{{tl\|wg\|RestOfVariableName}} for global variables
	*{{tl\|tag}} for a quick way to mention an XML-style tag in a preformatted		*{{tl\|tag}} for a quick way to mention an XML-style tag in a preformatted
	== Translations ==
			==Translations==
	All pages on mediawiki.org are candidates for translation into multiple languages.		All pages on mediawiki.org are candidates for translation into multiple languages.
	MediaWiki.org is a multilingual wiki, it uses the [[Extension:Translate\|Translate extension]] to present alternative translations and [[Help:Extension:Translate/Page_translation_administration\|manage the translation of pages]].		MediaWiki.org is a multilingual wiki, it uses the [[Extension:Translate\|Translate extension]] to present alternative translations and [[Help:Extension:Translate/Page_translation_administration\|manage the translation of pages]].
Line 423:		Line 423:
	}}		}}

	== Further information ==		==Further information==

	*[[Documentation/Technical writer guide]]		*[[Documentation/Technical writer guide]]
	*[[Technical documentation prioritization]]		*[[Technical documentation prioritization]]

	== See also ==		==See also==

	*[[Web APIs hub/Contributing]] – guide to writing articles for third-party developers		*[[Web APIs hub/Contributing]] – guide to writing articles for third-party developers
Line 438:		Line 438:
	*[[Wikiversity:Technical writing]]		*[[Wikiversity:Technical writing]]

	== Footnotes ==		==Footnotes==

	{{Conventions navigation}}		{{Conventions navigation}}

	[[Category:Documentation{{\|<nowiki>translation:}}</nowiki>]]		<nowiki>[[Category:Documentation{{\|</nowiki><nowiki>translation:}}</nowiki>]]
			<references />

Tobyvan: /* Language */

2020-07-07T12:24:11Z

Language

Show changes

Tobyvan: Created page with " ==Overview== This page is a supplementary style guide for writing and editing technical documentation in MediaWiki and other te..."

2020-07-07T11:37:51Z

Created page with "<languages/> <translate> ==Overview==   This page is a supplementary style guide for writing and editing technical documentation in MediaWiki and other te..."

New page

<languages/>
<translate>
==Overview== 


This page is a supplementary style guide for writing and editing technical documentation in MediaWiki and other technical spaces.</translate>
<translate>

It is intended to provide tips for writing clear, concise technical documentation in plain language, to highlight best practices and standards for a variety of technical documents used across projects, to share resources and knowledge about technical writing and editing in general.


"Good" technical documentation makes it easier for individuals to make technical contributions across Wikimedia projects.</translate>
<translate>

Whether you consider yourself a writer or not, your contributions are needed and appreciated.

===English Wikipedia Manual of Style=== 


The [[<tvar|1>w:WP:MOS</>|English Wikipedia's Manual of style]] covers certain topics in detail (like punctuation) and summarizes the key points of others.</translate>
<translate>

It can be a useful reference for anyone writing or editing technical documentation in English across Wikimedia projects when no more specific guidelines exist on the local wiki.

=== Additional guidelines for technical writing and editing === 


It is important to follow clear standards and style guidelines for writing and editing documentation, especially when many individuals contribute to it with varying levels of skills and experience.</translate>
<translate>

There are many style and usage rules for general writing – far too many to remember – and even more for technical writing.</translate>
<translate>

This page provides basic guidelines and tips to help get you started, as well as some specific information not covered in the Wikipedia Manual of Style.
</translate>

{{TOC|align=right}}

<translate>
== Audience and content == 

=== Writing for technical audiences === 


Before you begin writing, it is important to think about the audience for your work.


* Who do you imagine will be reading this technical documentation?</translate>
<translate>

* Where are they coming from?</translate>
<translate>

* How familiar are they with the concepts you are presenting?</translate>
<translate>

* What might they need to know in order to understand?


Once you have an understanding of your audience, you will have a better sense of what you need to convey and how to convey it.
</translate>

{{tip|1=<nowiki/>
<translate>

* If you know your audience is ''highly technical and familiar'' with the processes you are describing, then you ''do not need to explain'' basic concepts.</translate>
<translate>

* If you know your audience is ''learning or unfamiliar'' with the processes you are describing, then ''include explanations'' of basic concepts ''and links'' to additional information.
</translate>
}}

<translate>
=== Writing with a purpose === 


What purpose will your technical documentation serve? There are many reasons to write documentation.</translate>
<translate>

It is helpful to know ''why'' you are writing and what your goal is before you begin.


* Is it to teach someone, like a newcomer, about a process or concept?</translate>
<translate>

* Is it to show someone how to follow a process?</translate>
<translate>

* Is it meant to provide background and context for a concept or process?</translate>
<translate>

* Is it a reference intended to provide information?

=== Writing within a context === 


When deciding what to write and how to frame it for your reader, it can help to define a context or occasion for your writing.</translate>
<translate>

Your communication takes place in the context of a bigger situation.</translate>
<translate>

The context may be bounded by the era you are writing in, the type of technology available, your geographical location and culture, or the current culture and communication styles of the community you and your readers belong to.</translate>
<translate>

The occasion may be personal and arise from the situation that motivated you to create or improve a piece of documentation.


For example, if you are writing technical documentation for Wikimedia projects, consider the culture created by the individuals who volunteer, and take part across them.</translate>
<translate>

How could you best position your writing within the context of this community and its culture to create the most meaningful and useful technical documentation?

=== User testing and feedback === 


Create technical documentation to communicate ideas and concepts to a real audience of users.</translate>
<translate>

Naturally, this audience should play a critical role in how the documentation is shaped and reshaped.</translate>
<translate>

Think about ways you can gather information about your users' experiences.</translate>
<translate>

Take some time to answer the following questions:


* Does your documentation include a mechanism for feedback?</translate>
<translate>

* Can you engage in timely conversations with the audience to make improvements?

=== Clarity and consistency === 


Your goal is to make accessing, reading, and creating technical documentation for MediaWiki/Wikimedia easier and more intuitive by promoting clarity and consistency throughout.</translate>
<translate>

Technical documentation is written for a wide audience and edited by a variety of contributors.


Voice, tone, grammar usage, style, and format should be consistent across technical documentation and similar content collections.</translate>
<translate>

This helps readers learn how to navigate information and makes it easier for contributors to understand how to edit and add new information.

=== Deciding on a document type === 
</translate>
{{see also|Documentation/Technical documentation templates and suggestions}}

<translate>

Identify your main audience, purpose, and context first to decide on the type of document you will create.
</translate>

{| class="wikitable"
|+
!Example Audience
!Purpose<ref>https://www.divio.com/en/blog/documentation/</ref>
!Potential Document Types
!Example
|-
|Newcomer interested in learning how to become a Toolforge user
|To learn
|Tutorial, FAQ, Getting Started guide
|[[wikitech:Help:FAQ#Cloud_VPS|Cloud VPS and Toolforge FAQ]]
|-
|Experienced technical contributor trying to work through a known problem
|To achieve a goal
|Walk-through, How-To guide
|[[wikitech:Help:Toolforge/My_first_Flask_OAuth_tool|My First Flask OAuth Tool]]
|-
|Individual trying to understand the history of ORES and how it evolved
|To understand
|Explanatory article, blog post
|[[wmfblog:2015/11/30/artificial-intelligence-x-ray-specs/|Artificial intelligence service “ORES” gives Wikipedians X-ray specs to see through bad edits]]
|-
|A person looking for a definition of SSH keys
|To inform
|Reference guide, glossary
|[[wikitech:Help:Glossary|Glossary]]
|}

== Language ==

{{see also|wikiversity:Technical_writing_style|label 1=The "Writing clearly" article on Wikiversity}}

This section briefly mentions some topics worth exploring elsewhere in more detail.
Always check your words and expressions against these criteria on [[wikt:|Wiktionary]]: Wiktionary entries cover hundreds of languages, explicitly state the grammatical and lexical features of words and their declensions, provide detailed context labels (including about jargon, UK vs. USA English) and expose how translatable terms are in hundreds of other languages.

=== Plain English ===

Please remember: many visitors to these pages are not native English speakers.

For documentation written in English, [[w:en:Plain English |Plain English]] works best.
Clear writing is the most understandable by diverse audiences, and is also easiest to translate.
There are a number of good tools for checking your writing, at [[m:Tech/News/Manual#Guidelines|Tech News' Writing Guidelines on Meta-Wiki.]]

'''Tips:'''

* Avoid ambiguity, jargon, and vague or complex wording.
* Use words your audience will understand, and enough words to convey your message.
* Define terms that may not be obvious to individuals who are new to the subject matter you are writing about.
* Keep paragraphs and sentences short and concise.
* Use contractions or don't. Be consistent.

=== Voice and tone ===

MediaWiki is a place where anyone can edit.
Thus, it can be difficult to maintain a consistent voice and tone in the documentation.

Consider using these elements in your writing:

{| class="wikitable"
!Voice and tone
!What this means
!Instead of this
!Try This
|-
|Friendly
|Technical documentation does not need to sound academic or dry. Write to your audience as if they are there in person.
|Before beginning, the user must create an account.
|Start by creating an account.
|-
|Professional
|Technical documentation can be friendly, but should remain professional.
|Don't make a bazillion changes.
|Try to make minimum changes.
|-
|Positive
|Avoid using negative sentence constructions. Explain things in terms of what to do. It is harder to mentally parse a complex negative sentence!
|''N'' won't happen, if you don't ''XYZ''.
|To make ''N'' happen, do ''XYZ''.
|-
|Active
|Try to use [[:en:Active voice|active voice]], except when diplomacy calls for [[:en:Passive voice|passive voice]].
|The extension must be registered.
|You must register the extension.
|-
|Non-gendered
|Adopt [[:en:Gender-neutral language|gender-inclusive language]]. Assume your audience comprises all gender identities.
|When he clicks Save
|When the user clicks Save
|-
|Inclusive
|Use alternatives to common words or phrases that may unintentionally reinforce inappropriate stereotypes.
|This UI is crazy.
|This UI could be improved.
|-
|Free of colloquialisms
|It can be confusing to use [[:en:Colloquialism|colloquialisms]], jokes, puns, or ''turns of phrase'' that non-native English speakers or individuals from other regions might not easily understand.
|Creating a user account is a piece of cake.
|It is easy to create a user account.
|}

{{Note|1=This is not meant to be an exhaustive list or a strict set of rules.}}

===Point of view===

* Use [[:en:Grammatical_person|second person]] ("You" or assumed "You") when addressing your audience.
* Avoid [[:en:Grammatical_person|first person]] ("I"), unless you are writing a FAQ with questions asked from the first person perspective.
* Use an [[:en:Imperative_mood|imperative mood]] for most documentation focused on goals or process.

== Structuring pages ==

=== Overview ===

All pages should include an overview section that explains:

# Purpose of the page
# Audience of the page
# Prerequisites the reader will need to know before proceeding (Ex. a working knowledge of Python)
# Software or tools the reader will need to complete the processes or tasks outlined on the page (Ex. Java installed)
# Use case, case study, a practical understanding of the product, service or tool in action. (optional)

=== Table of contents ===

* Each page should include a table of contents, so information can be accessed easily.

=== Titles and headers ===

* Use [[:en:Letter_case#Sentence_case | sentence case]] for headers.
* Keep header fonts consistent throughout documentation.
* Optional use of [[:en:Help:Link#Section_linking_(anchors)|anchors]] to link sections or subsections in the same page.

=== Information flow ===

Technical documentation pages should follow a consistent pattern across content collections.

'''An ideal pattern''' for each page might be:
* Page Title
* Introduction/Overview
* Header
** Content
*** Subhead if needed
**** Content

==Formatting text==

{{main|Help:Formatting}}

===Formatting code examples and other technical elements===

Many situations call for text to be formatted in a way that distinguishes code and other technical elements from regular text.

{| class="wikitable"
|+
!Purpose
!Wiki-Markup
!Result
!Situation
|-
|Code
|{{tag|code|content=code}}
|<code>code</code>
|Use for short strings of code, including wikitext markup.
Within {{Tag|code}}, use <code><nowiki>''</nowiki></code>italics<code><nowiki>''</nowiki></code> to indicate variables and sample names so users know what to replace.
|-
|Syntax highlight
|
<pre><syntaxhighlight lang="css">
.citation {
margin: 0;
}
</syntaxhighlight></pre>

Text before <code><nowiki><syntaxhighlight lang="css" inline></nowiki></code>.foo {margin: 0;}<code><nowiki></syntaxhighlight></nowiki></code> text after.
|<syntaxhighlight lang="css">
.citation {
margin: 0;
}
</syntaxhighlight>

Text before <syntaxhighlight lang="css" inline="">.foo {margin: 0;}</syntaxhighlight> text after.
|Use the {{tag|source|params=lang="''...''"}} tag to document a few lines of code, and preserve whitespace and linebreaks. The <code>inline</code> attribute allows using it within an existing paragraph.
Note you cannot use italic in the middle of a <code><nowiki><syntaxhighlight lang="foo">...</syntaxhighlight></nowiki></code> block, so you have to fall back to YOURPASSWORD or The_page_title to indicate variables.

See [[Extension:SyntaxHighlight]] for more details.
|-
|Preformatted
|{{tag|pre|content=preformatted text
      with indent}}
|<pre>preformatted text
with indent</pre>
|Same as above (preserve whitespace and linebreaks), but without coloring.
|-
|Keyboard input
|{{tag|kbd|content=keyboard 123}} (vs keyboard 123)
|<kbd>keyboard 123</kbd> (vs keyboard 123)
|Use {{tag|kbd}} for actual keyboard input - the text a user types into an input field or at a terminal command line. It displays in plain monospace.
|-
|Variables
|{{tag|var|content=variable}
<code><nowiki>''</nowiki></code>italics<code><nowiki>''</nowiki></code>
|<var>variable</var>
''italics''
|Use italics for variables like ''message-key-name'' and sample names like ''My page title''.
Do not use punctuation such as <YOURPASSWORD>, because readers don't know the angle brackets are noise and will type them.
|-
|Bold
|<code><nowiki>'''</nowiki></code>bold<code><nowiki>'''</nowiki></code>
|'''bold'''
|Generally only used for the first instance of the page-title, and for rare emphasis of keywords to enable easier skimming of lists or paragraphs.

Note: Sometimes '''bold''' is '''overused''' for emphasis.
You may consider using a template instead, e.g. {{tl|Caution}}, {{tl|Note}}, or {{tl|Warning}}.
|-
|Quotations
|<code>"</code>quotation marks<code>"</code>

Text before

{{tag|blockquote|content=blockquote}}

Text after
|"quotation marks"

Text before<blockquote>blockquote</blockquote>Text after
|Use quotation marks for brief pieces of content quoted from other sources.

Use blockquote for longer pieces of content.
|-
|Abbreviations
|JavaScript (JS)

<code><nowiki><abbr title="JavaScript">JS</abbr></nowiki></code>
|JavaScript (JS)

<abbr title="JavaScript">JS</abbr>
|You should define abbreviations the first time they are used. Use either plain text and parentheses, or the HTML abbr tag.
|-
|Keypress
|<code>{{tl|key press|Ctrl|Shift|I}}</code>
|{{key press|Ctrl|Shift|I}}
|Showing specific keyboard presses or combinations. Extensive examples in [[Special:MyLanguage/VisualEditor/Portal/Keyboard shortcuts|VisualEditor/Portal/Keyboard shortcuts]].

Note: This template might not exist on other wikis.
|-
|Button
|<code>{{tl|Button|<nowiki>{{int|showpreview}}</nowiki>}}</code>
|{{button|{{int|showpreview}}}}
|Showing UI buttons that need to be clicked on.

Note: This template might not exist on other wikis.
|}

=== Links ===

{{main|Help:Links}}

{| class="wikitable"
|+
!Type
!Purpose
!How to implement
!Example
|-
|Local
|Link to other MediaWiki pages
|
* <code><nowiki>[[Foo]]</nowiki></code>
* <code><nowiki>[[Foo|Bar]]</nowiki></code>
|[[MediaWiki]]
|-
|Translated Target
|Link to other ''translated'' MediaWiki pages
|<code><nowiki>[[Special:MyLanguage/Foo|Foo]]</nowiki></code>
|[[Special:MyLanguage/How_to_contribute|How to contribute]]
|-
|Interwiki
|Link to page belonging to a different Wikimedia project
|
* <code><nowiki>[[</nowiki>phab:''T2001''<nowiki>]]</nowiki></code> for tasks and project tags
* <code><nowiki>[[</nowiki>mail:''wikitech-l''<nowiki>]]</nowiki></code> for mailing lists
* <code><nowiki>[[</nowiki>w:en:''foobar''<nowiki>]]</nowiki></code> to English Wikipedia articles
* <code><nowiki>[[</nowiki>wikitech:''foobar''<nowiki>]]</nowiki></code> for details about the WMF cluster.
|[[w:en:Documentation|Documentation page on Wikipedia]]
|-
|External
|Link to external pages
|<code><nowiki>[https://www.example.org Example.org]</nowiki></code>
|[https://dictionary.cambridge.org/dictionary/english/example Example]
|}

<translate>
=== Templates === 
</translate>
{{See also|Documentation/Style guide/templates}}

Templates are often used on Mediawiki.org pages.
Templates can help to maintain consistency and can make it easier to translate information.

Below are some common templates:

* {{tl|ApiEx}} for api.php request URLs
* {{tl|Api help}} to transclude generated API documentation
* {{tl|caution}}, {{tl|fixtext}}, {{tl|note}}, {{tl|tip}}, {{tl|todo}}, and {{tl|warning}} for styles of inline highlight boxes
* {{tl|fixme}}, {{tl|historical}}, {{tl|notice}}, {{tl|outdated}}, and {{tl|update}} for page/section message boxes
* {{tl|class doclink}}, {{tl|file doclink}}, and {{tl|js doclink}} to link to MediaWiki core's [https://doc.wikimedia.org/mediawiki-core/master/php/ generated documentation]
* {{tl|git file}} to link to source code
* {{tlx|irc|wikimedia-tech}} for IRC link
* {{tl|Key press}} for, e.g. {{Key press|Ctrl|Shift|I}}, and {{tl|button}} for, e.g. {{button|{{int|showpreview}}}}
* {{tl|main}} and {{tl|see also}} for page/section hatnotes (a short note placed at the top of an article)
* {{tl|MW file}} for a box with info and links for a file in MediaWiki core
* {{tl|ptag}} for the top-right-of-page phabricator project tag
* {{tl|tracked}} for the related Phabricator task
* {{tl|wg|RestOfVariableName}} for global variables
* {{tl|tag}} for a quick way to mention an XML-style tag in a preformatted way

<translate>
== Translations == 
</translate>
All pages on mediawiki.org are candidates for translation into multiple languages.
MediaWiki.org is a multilingual wiki, it uses the [[Extension:Translate|Translate extension]] to present alternative translations and [[Help:Extension:Translate/Page_translation_administration|manage the translation of pages]].

{{tips|1=
<translate>

* If a page has been translated, then click 'Edit source' to edit the entire page.</translate> <translate> [[<tvar|1>Special:MyLanguage/Help:Extension:Translate/Page_translation_administration#Markup_examples</>|Wrongly placed]] translation tag markers around section headings can confuse section editing, and as of July 2015 VisualEditor does not understand the following tags:</translate> {{tag|languages|open}}, {{tag|translate|open}}, {{tag|tvar|open}}
<translate>

* Do not copy and paste existing markup.</translate> <translate> If in doubt, focus on writing a good text and let someone else handle the Translate markup.</translate>
}}

<translate>
== Further information == 
</translate>
*[[Documentation/Technical writer guide]]
*[[Technical documentation prioritization]]

<translate>
== See also == 
</translate>
*[[Web APIs hub/Contributing]] – guide to writing articles for third-party developers
* Some other technical documentation style guides:
** [https://rackerlabs.github.io/docs-rackspace Rackspace Style Guide]
** [https://developer.gnome.org/gdp-style-guide/ Gnome Documentation Style Guide]
** [https://developers.google.com/style/ Google Developer Documentation Style Guide]
** [https://developer.wordpress.com/themes/documentation-style-guide/ Wordpress Documentation Style Guide]
*[[Wikiversity:Technical writing]]

<translate>
== Footnotes == 
</translate>
<references />

{{Conventions navigation}}

[[Category:Documentation{{#translation:}}]]