diff options
Diffstat (limited to 'files/pt-pt/mdn/guidelines/does_this_belong_on_mdn/index.html')
| -rw-r--r-- | files/pt-pt/mdn/guidelines/does_this_belong_on_mdn/index.html | 201 |
1 files changed, 201 insertions, 0 deletions
diff --git a/files/pt-pt/mdn/guidelines/does_this_belong_on_mdn/index.html b/files/pt-pt/mdn/guidelines/does_this_belong_on_mdn/index.html new file mode 100644 index 0000000000..dc76b00182 --- /dev/null +++ b/files/pt-pt/mdn/guidelines/does_this_belong_on_mdn/index.html @@ -0,0 +1,201 @@ +--- +title: Isto pertence aos MDN Web Docs? +slug: MDN/Guidelines/Does_this_belong_on_MDN +tags: + - Guía + - Linhas Diretrizes + - Metadados MDN +translation_of: MDN/Guidelines/Does_this_belong_on_MDN +original_slug: MDN/Guidelines/Isto_pertence_a_MDN +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/pt-PT/docs/MDN")}}</div> + +<p><span class="seoSummary">Neste artigo, irá encontrar informação a descrever como decidir se determinado tópico e/ ou tipo de conteúdo deverá ou não ser incluído na MDN Web Docs. Nós também iremos considerar outros lugares em que pode colocar o conteúdo, embora não em profundidade</span>.</p> + +<h2 id="A_questão">A questão</h2> + +<p>If you're preparing to document something, you may be trying to decide whether to put the information on MDN Web Docs. In addition, you may be considering maintaining documentation in your source code, putting the document on the <a href="https://wiki.mozilla.org/">Mozilla wiki</a>, or in readme files in a Git repository. This article's purpose is to help you decide which of these options is right for your content.</p> + +<p>The two main considerations for whether a document belongs on MDN are:</p> + +<ul> + <li>The topic of the document (what is it about?)</li> + <li>The nature of the document (what kind of document is it?)</li> +</ul> + +<p>Be aware that all contributions to MDN fall under specific open source licenses; these are <a href="https://developer.mozilla.org/en-US/docs/MDN/About#Copyrights_and_licenses">described in detail</a> on our <a href="/en-US/docs/MDN/About">About MDN</a> page.</p> + +<div class="note"> +<p><strong>Nota</strong>: Keep in mind that Mozilla's <a href="https://www.mozilla.org/en-US/about/legal/terms/mozilla/">Websites & Communications Terms of Use</a> are in effect when you use or contribute to MDN Web Docs. Review this document to ensure that you're aware of what can and cannot be posted on Mozilla sites.</p> +</div> + +<h2 id="Que_tópicos_pertencem_aos_MDN_Web_Docs">Que tópicos pertencem aos MDN Web Docs?</h2> + +<p>In general, if it's an open web-facing technology, we document it on MDN. This means any feature that can used by Web developers creating sites and applications now and in the near future. If it is implemented by multiple browsers and either accepted as standard or is progressing towards standardization, then yes, definitely. If it is still very experimental and not implemented in multiple browsers and/or liable to change, then it is still suitable for inclusion, but may not be seen as a priority for the writer's team to work on.</p> + +<p>The primary focus is on front-end web technologies:</p> + +<ul> + <li><a href="/en-US/docs/Web/HTML" title="HTML">HTML</a></li> + <li><a href="/en-US/docs/Web/CSS" title="CSS">CSS</a></li> + <li><a href="/en-US/docs/Web/JavaScript" title="en/JavaScript">JavaScript</a></li> + <li><a href="/en-US/docs/Web/SVG" title="SVG">SVG</a></li> + <li><a href="/en-US/docs/Web/API">Web APIs</a></li> + <li><a href="/en-US/docs/Web/API/WebGL_API" title="WebGL">WebGL</a></li> + <li>etc.</li> +</ul> + +<div class="note"> +<p><strong>Nota</strong>: Back-end technologies usually have their own documentation elsewhere that MDN does not attempt to supercede, although we <a href="https://developer.mozilla.org/en-US/docs/Learn/Server-side">do have some exceptions</a>.</p> +</div> + +<p>Also welcome are topics that cut across technologies but are relevant to Web development, such as:</p> + +<ul> + <li><a href="/en-US/docs/Web/Accessibility" title="Accessibility">Accessibility</a></li> + <li><a href="/en-US/docs/AJAX">AJAX</a></li> + <li><a href="/en-US/docs/Web/Guide/Graphics">Web graphics</a></li> + <li><a href="/en-US/docs/Apps">Open web apps</a></li> + <li><a href="/en-US/Apps/Tutorials/Games">Web-based games</a></li> +</ul> + +<div class="note"> +<p><strong>Nota:</strong> MDN covers some non-standard features if they're exposed to the Web, especially if they find common usage; for example, we have documentation for WebKit-specific CSS properties.</p> +</div> + +<h2 id="Que_tópicos_não_pertencem_aos_MDN_Web_Docs">Que tópicos não pertencem aos MDN Web Docs?</h2> + +<p>In general, anything that isn't an open web standard does not belong on MDN. The below sections provide more specifics.</p> + +<h3 id="Produtos_da_Mozilla">Produtos da Mozilla</h3> + +<p>Documentation in this category includes information on both how to work with Mozilla products, as a developer, and how to contribute to these open-source projects.</p> + +<p>While MDN Web Docs contains a large quantity of Mozilla product documentation, the focus of new content development is on open web standards. We are in the process of determining what to do about this content, so it may not make sense to create new Mozilla product documentation on MDN Web Docs. If you are working on a Mozilla product (or project that may become a product), talk to a member of the <a href="https://wiki.mozilla.org/Engagement/MDN_Durable_Team">MDN staff team</a> to discuss possible avenues for documenting your product. Also, see the section on <a href="#Cases_for_documenting_elsewhere">Cases for documenting elsewhere</a>, below.</p> + +<ul> + <li><a href="en-US/docs/Firefox">Firefox browser</a> + + <ul> + <li><a href="/en-US/docs/Tools">Firefox Developer Tools</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons">Add-ons</a></li> + <li><a href="en-US/docs/Mozilla/Developer_guide/Build_Instructions">Building and configuring Firefox</a></li> + <li>etc.</li> + </ul> + </li> + <li><a href="/en-US/docs/Mozilla">The Mozilla platform</a> + <ul> + <li><a href="/en-US/docs/Mozilla/Gecko">Gecko</a></li> + <li><a href="/en-US/docs/Mozilla/Projects/SpiderMonkey">SpiderMonkey</a></li> + <li>etc.</li> + </ul> + </li> +</ul> + +<h3 id="E_que_mais">E que mais?</h3> + +<p>Other examples of inappropriate topics for MDN Web Docs:</p> + +<ul> + <li>Technology that is not exposed to the Web and is specific to a non-Mozilla browser.</li> + <li>Technology that is not related to the Web or Mozilla products.</li> + <li>Documentation for end-users; for Mozilla products, such documentation belongs on the <a href="https://support.mozilla.org">Mozilla support site</a>.</li> +</ul> + +<h2 id="Que_tipos_de_documentos_pertencem_à_MDN">Que tipos de documentos pertencem à MDN?</h2> + +<p>In general, MDN is for <em>product</em> documentation, not for <em>project</em> or <em>process</em> documentation (except <a href="/en-US/docs/MDN">about MDN itself</a>). So, if the document is about "how to use a thing" or "how a thing works" (where the "thing" is in one of the topic categories mentioned above), then it can go on MDN. But if it about "who's working on developing a thing" or "plans for developing a thing", then it shouldn't go on MDN. In that case, if the thing is being developed under the umbrella of Mozilla, then the <a href="https://wiki.mozilla.org/Main_Page">Mozilla project wiki</a> may be a good place for it.</p> + +<p>Here are some examples of types of documents that should <em>not</em> be placed on MDN<strong>:</strong></p> + +<ul> + <li>Planning documents</li> + <li>Design documents</li> + <li>Project proposals</li> + <li>Specifications or standards</li> + <li>Promotional material, advertising, or personal information{{ref("*")}}</li> +</ul> + +<h2 id="Vantagens_para_documentar_na_MDN">Vantagens para documentar na MDN</h2> + +<p>If you've determined that the documentation you want to write is appropriate in content and type for MDN, but you're still not sure whether MDN is the best place for it, read on. There are a lot of good reasons to create documentation on MDN.</p> + +<h3 id="Muitos_escritores_e_tradutores">Muitos escritores e tradutores</h3> + +<p>The MDN community is big. We have a lot of people that participate in creating and maintaining content on MDN. With writers and editors on every continent (okay, maybe not Antarctica, but otherwise), there's a lot of value to the sheer volume of writers:</p> + +<ul> + <li>We have a paid staff of writers whose <strong>mission</strong> is to make sure that our content is as good as possible.</li> + <li>We have a core community of volunteers who contribute substantial amounts of content and can help you.</li> + <li>The MDN team can work with you to ensure that your documentation project is adequately staffed.</li> + <li>The broader MDN community also contributes enormously, from typo fixes to editorial reviews of your content.</li> + <li>The <a href="https://chat.mozilla.org/#/room/#mdn:mozilla.org">MDN Web Docs chat room</a> offers a resource where you can talk to our writing community and get their advice, or recruit help with the production of or maintenance of your content.</li> + <li>Because we have contributors all over the world, there's always someone around, watching for problems and fixing them.</li> + <li>Our community of volunteers includes translators for many languages, who can help localize your documentation.</li> +</ul> + +<p>Do you want your development team to be entirely responsible for the production of documentation? That's likely if your documentation is maintained elsewhere.</p> + +<h3 id="Manutenção">Manutenção</h3> + +<p>Because of the sheer number of contributors, there's usually someone on hand to watch for problems with your content: from spam control to copy-editing, things can happen around the clock. Here's just a taste of what our team can do:</p> + +<dl> + <dt>Delete spam</dt> + <dd>Spam happens. We deal with it.</dd> + <dt>Copy editing</dt> + <dd>You don't have to worry if your writing isn't as clear or precise as you'd like. We'll turn your prose into something other people can read.</dd> + <dt>Consistency of style</dt> + <dd>We'll ensure that your content is stylistically consistent not just within itself, but with the other documentation around it.</dd> + <dt>Content management</dt> + <dd>Our team will help ensure that the documentation is cross-linked with other relevant materials, that articles are put in the right places, and that menus and other infrastructure is built to make it easy to follow and understand.</dd> + <dt>Site and platform maintenance</dt> + <dd>MDN has both an IT team which keeps the site up, running, and secure, and a platform development team to maintain and enhance the platform on which the content is presented. You won't need to devote your own or additional resources to documentation infrastructure.</dd> +</dl> + +<h2 id="Casos_para_documentação_em_qualquer_outra_parte">Casos para documentação em qualquer outra parte</h2> + +<p>There are also a few reasons you may be thinking about documenting your work somewhere other than MDN. Here are some of those reasons, and the pros and cons for each.</p> + +<h3 id="Planos_e_processos">Planos e processos</h3> + +<p>Documentation for plans, processes, and proposals should never be put on MDN. That's pretty simple. If your project is part of Mozilla, you can put them on the <a href="https://wiki.mozilla.org/Main_Page">Mozilla project wiki</a>.</p> + +<h3 id="O_projeto_está_no_GitHub">O projeto está no GitHub</h3> + +<p>Some of Mozilla's projects are hosted on GitHub, and GitHub offers its own wiki-like system for documentation. Some teams like to produce their documentation there. This is certainly fair and convenient if you're game to write your own docs; however, keep in mind that:</p> + +<ul> + <li>The MDN Web Docs team will probably not be able to help you. We don't generally participate in documentation work off MDN Web Docs; there are exceptions but they are exceptionally rare.</li> + <li>Cross-linking your documentation with other relevant materials may be difficult or impossible.</li> + <li>The content will not have consistent style with other documentation.</li> + <li>Your documentation loses discoverability by not being among other (Web or Mozilla) documentation.</li> +</ul> + +<p>It's possible, of course, that these things don't bother you, or aren't a problem in your situation. Some teams don't mind writing and maintaining their own docs, or are working on code that has minimal documentation needs.</p> + +<h3 id="Quer_manter_os_documentos_na_fonte">Quer manter os documentos na fonte</h3> + +<p>Some teams like to have their documentation in the source tree. This is particularly common with project internals and library projects.</p> + +<p>This approach has a couple of advantages:</p> + +<ul> + <li>It lets the developers document their technology as they code it, helping to ensure that the docs stay up to date with the code.</li> + <li>Docs can be subject to the same development and release processes as the code, including versioning.</li> +</ul> + +<p>There are some drawbacks:</p> + +<ul> + <li>The MDN Web Docs team can't help you; even if the code is within Mozilla's source repository, the system of reviews and check-ins make it impractical for the docs team to participate.</li> + <li>You don't have easy tools for cross-linking with other relevant documentation. Cross-linking provides both context and additional important information to your readers.</li> + <li>Your documentation loses discoverability by not being among other documentation.</li> + <li>Even if you use conversion tools (like JavaDoc) to create Web-readable documentation, it won't be as attractive as what we can do on MDN Web Docs.</li> +</ul> + +<p>Still, this can be a viable option (possibly even a good option) for some types of projects, especially small ones or those that aren't expected to get much interest.</p> + +<p>{{endnote("*")}} It's OK to put a limited amount of personal information on your MDN profile page. User profiles should reflect a human being, not a business or organization. A moderate degree of self-promotion is OK, but link-spamming is not. Please <em>do not </em>use your profile to upload personal photos or other irrelevant files.</p> |