Documentação/Guia de estilo

O seguinte guia de estilo fornece diretrizes para a elaboração e edição de documentação técnica no MediaWiki e em outros espaços técnicos. Ele visa ajudar-lhe a escrever documentação técnica de forma clara e concisa e em linguagem acessível, além de fornecer-lhe recursos adicionais sobre a elaboração e a edição de documentos técnicos em geral.

Uma boa documentação técnica faz com que mais pessoas possam contribuir com os projetos da Wikimedia. É importante seguir normas claras e diretrizes de estilo ao elaborar a documentação, especialmente quando os leitores e contribuidores possuem níveis diferentes de experiência e habilidade. Não importa se você considera suas habilidades de escritas boas ou não; suas contribuições são sempre bem-vindas e valorizadas!

O manual de estilo da Wikipédia anglófona cobre detalhadamente tópicos diversos (até pontuação!), e sumariza os pontos principais dos outros guias de estilo. É uma referência bem útil se você estiver preparando-se para escrever documentação técnica em inglês nos projetos da Wikimedia, especialmente se sua wiki local não possui diretrizes mais específicas.

Essa página fornece sugestões e diretrizes básicas para que você possa familiarizar-se com documentação técnica. Ela inclui informações específicas à documentação que não estão cobertas no manual de estilo mencionado acima.

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

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. Your communication takes place in the context of a bigger situation. 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 your readers. 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 participate in those projects. 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?

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. Think about ways you can gather information about your users' experiences. Take some time to answer the following questions:

• Can you use forums like Stack Overflow or mailing lists to check if your document answers the most common questions people have about your specific topic?

Clarity and consistency makes it easier to access, read, and create technical documentation across MediaWiki/Wikimedia projects. 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. This helps readers learn how to navigate information and makes it easier for contributors to understand how to edit and add new information.

This section briefly mentions some topics worth exploring elsewhere in more detail. Always check your words and expressions against these criteria on 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.

For documentation written in English, Plain English (also called plain language) 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 Tech News' Writing Guidelines on Meta-Wiki.

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

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

• Always use the full, four-digit year.
• Use absolute dates ("in May 2037") instead of relative dates ("next year in May").
• Avoid adding dates that will require regular manual updates. Example: Write {{#time: Y }} instead of 2024 when referring to the current year, no matter what year it is currently.

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

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

• Use sentence case for headings.
• Keep heading fonts consistent throughout documentation.
• Optional use of anchors to link sections or subsections in the same page.
• Add a blank line after section headings. This impacts how the content is packaged for translation.
• Do not put a heading before your overview or lead section.

• Page title
• Introduction/Overview
• Heading
  • Content
    • Subheading if needed
      • Content

<syntaxhighlight lang="css">
.citation {
    margin: 0;
}
</syntaxhighlight>

.citation {
    margin: 0;
}

preformatted text
      with indent

''italics''

'''bold'''

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

• {{Atenção }}, {{Fixtext }}, {{Note }}, {{Tip }}, {{Todo }}, {{Atenção/núcleo }} - for styles of inline highlight boxes
• {{Fixme }}, {{Historical }}, {{Notice }}, {{Outdated }}, {{Atualizar }} - for page/section message boxes
• {{Main }}, {{See also }} - for page/section hatnotes (a short note placed at the top of an article)

• {{Class doclink }}, {{File doclink }}, {{Js doclink }} - to link to MediaWiki core's generated documentation
• {{MW file }} - for a box with info and links for a file in MediaWiki core
• {{Git file }} - to link to source code

• {{Ptag }} - for the top-right-of-page Phabricator project tag
• {{Rastreado }} - for the related Phabricator task

• {{irc|wikimedia-tech}} - for IRC link
• {{Key press }} - for, e.g. Ctrl+⇧ Shift+I, and {{Button }} for, e.g. Mostrar previsão
• {{ApiEx }} - for api.php request URLs
• {{Api help }} - to transclude generated API documentation
• {{Wg }} - for global variables
• {{Tag }} - for a quick way to mention an XML-style tag in a preformatted way

All pages on mediawiki.org are candidates for translation into multiple languages. MediaWiki.org is a multilingual wiki, it uses the Translate extension to present alternative translations and manage the translation of pages.

• Some other technical documentation style guides:
  • Google Developer Documentation Style Guide
  • MDN Web Docs Writing Style Guide
• Wikiversity:Technical writing
• Other language related resources:
  • Inclusive language
  • word-list
  • Naming things