diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..d5d660b --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "restructuredtext.confPath": "${workspaceFolder}" +} \ No newline at end of file diff --git a/conf.py b/conf.py index c93711e..202ccd7 100644 --- a/conf.py +++ b/conf.py @@ -36,7 +36,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'env'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'env', 'venv'] # -- Options for HTML output ------------------------------------------------- @@ -70,3 +70,11 @@ master_doc = 'index' html_favicon = "favicon.png" + +# -- Options for internationalization ---------------------------------------- + +# According official guide +# https://docs.readthedocs.io/en/stable/guides/manage-translations.html + +gettext_uuid = True +gettext_compact = False diff --git a/locales/pt_BR/LC_MESSAGES/README.mo b/locales/pt_BR/LC_MESSAGES/README.mo new file mode 100644 index 0000000..dc81a4f Binary files /dev/null and b/locales/pt_BR/LC_MESSAGES/README.mo differ diff --git a/locales/pt_BR/LC_MESSAGES/README.po b/locales/pt_BR/LC_MESSAGES/README.po new file mode 100644 index 0000000..8c8690c --- /dev/null +++ b/locales/pt_BR/LC_MESSAGES/README.po @@ -0,0 +1,39 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2017-2021, Daniele Procida +# This file is distributed under the same license as the Diátaxis package. +# SeuPedro , 2021. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Diátaxis \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2021-04-18 20:02-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.9.0\n" + +#: ../../README.rst:4 f6f4b7b8e0934815a89b2753213133b2 +msgid "The documentation system" +msgstr "O sistema de documentação" + +#: ../../README.rst:6 11bd1a25a955485a817877fbefdf21b6 +msgid "" +"A comprehensive and practical system that can help maintainers of product" +" documentation." +msgstr "" +"Um sistema prático e compreensivo que pode ajudar mantenedores de documentação" +" de produto" + +#: ../../README.rst:8 b0597666e31a4ea199af1f604640edeb +msgid "Published at https://diataxis.fr" +msgstr "Publicado em https://diataxis.fr" + +#: ../../README.rst:10 e7c566cb3fa048e5b0ee468cc7dbb2b7 +msgid "Author: Daniele Procida" +msgstr "Autor: Daniele Procida" + diff --git a/locales/pt_BR/LC_MESSAGES/adoption.mo b/locales/pt_BR/LC_MESSAGES/adoption.mo new file mode 100644 index 0000000..ca332d3 Binary files /dev/null and b/locales/pt_BR/LC_MESSAGES/adoption.mo differ diff --git a/locales/pt_BR/LC_MESSAGES/adoption.po b/locales/pt_BR/LC_MESSAGES/adoption.po new file mode 100644 index 0000000..5c401fa --- /dev/null +++ b/locales/pt_BR/LC_MESSAGES/adoption.po @@ -0,0 +1,272 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2017-2021, Daniele Procida +# This file is distributed under the same license as the Diátaxis package. +# FIRST AUTHOR , 2021. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Diátaxis \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2021-04-18 20:02-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.9.0\n" + +#: ../../adoption.rst:1 07acaa79c7e04864af68ee4e7987cd1c +msgid "" +"Adopted by IBM LoopBack, Cloudflare and dozens of other products and " +"projects, the Diátaxis framework provides a lightweight and flexible " +"architecture for technical documentaion." +msgstr "" + +#: ../../adoption.rst:1 b59c47c94bc5483d9b0cc735185835d2 +msgid "documentation, four, kinds" +msgstr "" + +#: ../../adoption.rst:10 124a8963b3124a04b26c78ac077b0b2f +msgid "Adoption of the framework" +msgstr "" + +#: 3cb3e785dbe4496d8cbe16c7511e60a8 +msgid "Not listed here?" +msgstr "" + +#: ../../adoption.rst:14 9949cb6a41b142c9907de68afc0778fb +msgid "" +"If you're using the system, or are in the process of adopting it, please " +"let us know if you'd like to be listed here." +msgstr "" + +#: ../../adoption.rst:17 94475663390c42d6b8a9955ac3d3f0df +msgid "" +"This is an incomplete list of projects, products and organisations that " +"have adopted the system in their own bodies of documentation. In some " +"cases the adoption remains partial or is still a work in progress." +msgstr "" + +#: ../../adoption.rst:20 65a40b25037b4f5ab2007ada7e464cfb +msgid "" +"`BrachioGraph `_, the cheapest, simplest " +"pen-plotter" +msgstr "" + +#: ../../adoption.rst:21 6fcfb0f24cd7492cbe9d3c98d8a65fcf +msgid "" +"`BeeWare `_, the write-once-deploy-anywhere project," +" for `Toga `_, `Briefcase " +"`_, `Rubicon `_ and `Rubicon Java `_." +msgstr "" + +#: ../../adoption.rst:24 76ec5d5ef72749b1bdefa0ed97bc0591 +msgid "Bosch (internal)" +msgstr "" + +#: ../../adoption.rst:25 d1f48794d77a4d759f2d3b5447facfe4 +msgid "`Ciw `_, the discrete event simulation library" +msgstr "" + +#: ../../adoption.rst:26 cf5d0a8c679844d0a5a522d19ec8279e +msgid "" +"`Cloudflare Workers docs `_ (related article, `New and improved Workers Docs " +"`_)" +msgstr "" + +#: ../../adoption.rst:28 de8a57090db84e1fb56473e44e4810d4 +msgid "`corrux `_ (internal)" +msgstr "" + +#: ../../adoption.rst:29 971418744f894c4d985b7a407c5aa60a +msgid "`Divio `_" +msgstr "" + +#: ../../adoption.rst:30 646db1bf5d104bef96eb0678210d08c4 +msgid "" +"`Django `_" +msgstr "" + +#: ../../adoption.rst:31 c37cd1679c3f4515a4e0a26347f9ac1e +msgid "`django CMS `_" +msgstr "" + +#: ../../adoption.rst:32 01ecd5b51bdd400fbb926240016b3aa1 +msgid "" +"`edo `_, a library for Evolutionary Dataset " +"Optimisation" +msgstr "" + +#: ../../adoption.rst:33 e0f8b3e004e44bc6956544dc32dbcd25 +msgid "" +"`Encore `_, a framework for rapid backend " +"development" +msgstr "" + +#: ../../adoption.rst:34 f843e0e631be40d984653d7bc7f25aa3 +msgid "Ericsson (internal)" +msgstr "" + +#: ../../adoption.rst:35 bb100f1c15154ab4940d1ed313e42b67 +msgid "" +"`Gensim `_, " +"`How to Author Gensim Documentation " +"`_" +msgstr "" + +#: ../../adoption.rst:37 18f4ec4df0654e4d82b9d9bffc681265 +msgid "`Gorgonia `_, a deep learning library for Go" +msgstr "" + +#: ../../adoption.rst:38 0a69f97fb67848fea6984f7c1dbebed4 +msgid "`Lisk `_" +msgstr "" + +#: ../../adoption.rst:39 b82c12b087244873afefee028c0c6219 +msgid "`Livepeer `_" +msgstr "" + +#: ../../adoption.rst:40 9ccd38e70b144fb9b4e03cb2c4e3f7b3 +msgid "" +"`LootLocker `_, a backend for independent " +"games development" +msgstr "" + +#: ../../adoption.rst:41 80c70f0ee55e4439b053baa498b85316 +msgid "" +"`Matching `_, a games theory resource " +"allocation library" +msgstr "" + +#: ../../adoption.rst:42 9f41ab3a70a949d7b37472820b5f9478 +msgid "" +"`mosromgr `_, a Python library for " +"managing TV and radio running orders, from `BBC News Labs " +"`_" +msgstr "" + +#: ../../adoption.rst:43 6ee6f29ea4a5498e91dd43244b78bb4d +msgid "" +"`NashPy `_, a Python mathematical library " +"for computing Nash equilibria" +msgstr "" + +#: ../../adoption.rst:44 9187651f0ce241819716d5ac056237ed +msgid "" +"`nbchkr `_, a system for assessing " +"students' assignments in Jupyter Notebooks" +msgstr "" + +#: ../../adoption.rst:45 3d649162ff434fe5905d88011d75adcf +msgid "" +"`NumPy `_, the scientific Python library " +"(related article, `Documentation as a way to build Community " +"`_)" +msgstr "" + +#: ../../adoption.rst:47 06c13e7e27904051a931787d255f4f3d +msgid "`PDFminer.six `_" +msgstr "" + +#: ../../adoption.rst:48 c73e12b1349746a3b44eb3c3d1283261 +msgid "`PostgREST `_" +msgstr "" + +#: ../../adoption.rst:49 0de031facbe04515926ae681683b83c4 +msgid "`PIconnect `_" +msgstr "" + +#: ../../adoption.rst:50 0a2b9b52a4074302a051cc3f8ef58258 +msgid "" +"`Snowpack `_, a frontend build tool, designed " +"for the modern web" +msgstr "" + +#: ../../adoption.rst:51 1e1f17931790480e9940db796a3dbc88 +msgid "`Sourcegraph `_, Universal code search" +msgstr "" + +#: ../../adoption.rst:52 0f6fdf28f7824ed1b08b8f69f92dd394 +msgid "`StrongLoop/LoopBack `_ by IBM" +msgstr "" + +#: ../../adoption.rst:53 df91eb88ee094219a15ff7a3154a44d8 +msgid "`TerminusDB `_" +msgstr "" + +#: ../../adoption.rst:54 153979f0ca1f4db094d5be51b81daa00 +msgid "Tesla Motors (internal)" +msgstr "" + +#: ../../adoption.rst:55 4dab6d1ad694427fb637a13780f8887e +msgid "`WebAccess/DMP `_" +msgstr "" + +#: ../../adoption.rst:56 73b707ac7e8a4874b790eaeff8fdbe68 +msgid "" +"`Wechaty `_: A Conversational RPA SDK for " +"Chatbot Makers" +msgstr "" + +#: ../../adoption.rst:57 c690b236a0f447588c633f06aa28f2f0 +msgid "Zalando (internal)" +msgstr "" + +#: ../../adoption.rst:61 848e5e7246d743ba9eedf7a06d84908e +msgid "Other mentions and references of interest" +msgstr "" + +#: ../../adoption.rst:63 b2c39bbac21b4e5c83e521ba40a7d5c7 +msgid "" +"`Django Axes proposal `_" +msgstr "" + +#: ../../adoption.rst:64 3e54f775dd5c413d8166d770959e6cc3 +msgid "" +"`GitLab " +"`_, `GitLab's Data Team documentation guide " +"`_" +msgstr "" + +#: ../../adoption.rst:67 230822b2d61f4984b3835fa90b9d7528 +msgid "" +"`Julia language proposal " +"`_" +msgstr "" + +#: ../../adoption.rst:68 c8dafe0d17ff4e2a91bbb14c6c502212 +msgid "" +"`Why You Should Document Your Work As a Data Scientist " +"`_" +msgstr "" + +#: ../../adoption.rst:69 e2630261a64b4744b2af16d11b62732e +msgid "" +"`Koninglijke Biblioteek (National Library of the Netherlands) research " +"software lab `_" +msgstr "" + +#: ../../adoption.rst:71 8abe63fbc86049d085f911265e2a1e1d +msgid "" +"`Tutorials in Jenkins user documentation " +"`_" +msgstr "" + +#: ../../adoption.rst:73 bc7445c2ba88490291a1aefd20ef68ee +msgid "" +"`TYPO3 `_" +msgstr "" + diff --git a/locales/pt_BR/LC_MESSAGES/explanation.mo b/locales/pt_BR/LC_MESSAGES/explanation.mo new file mode 100644 index 0000000..ca332d3 Binary files /dev/null and b/locales/pt_BR/LC_MESSAGES/explanation.mo differ diff --git a/locales/pt_BR/LC_MESSAGES/explanation.po b/locales/pt_BR/LC_MESSAGES/explanation.po new file mode 100644 index 0000000..d8b8bd4 --- /dev/null +++ b/locales/pt_BR/LC_MESSAGES/explanation.po @@ -0,0 +1,250 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2017-2021, Daniele Procida +# This file is distributed under the same license as the Diátaxis package. +# FIRST AUTHOR , 2021. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Diátaxis \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2021-04-18 20:02-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.9.0\n" + +#: ../../explanation.rst:4 8607b0adbc6e49a2a2e4cc4700ab85cd +msgid "About explanation" +msgstr "" + +#: ../../explanation.rst:8 bee5b73fbfb24ddea0c9dd9b20913a29 +msgid "" +"Explanation is **discussion** that clarifies and illuminates a particular" +" topic. Explanation is **understanding-oriented**." +msgstr "" + +#: ../../explanation.rst:11 5f3685ab984e4b508c585f99b9985953 +msgid "Explanations broaden the documentation’s coverage of a topic." +msgstr "" + +#: ../../explanation.rst:13 2f409f15df924a4ba4ca2bcc9fdf5f4a +msgid "" +"Explanations can equally well be described as *discussions*; they are " +"discursive in nature. They are a chance for the documentation to relax " +"and step back from the software, taking a wider view, illuminating it " +"from a higher level or even from different perspectives. You might " +"imagine a discussion document being read at leisure, rather than over the" +" code." +msgstr "" + +#: ../../explanation.rst:20 0ff000a1993749ccba67b401ed6dc796 +msgid "" +"This section of documentation is rarely explicitly created, and instead, " +"snippets of explanation are scattered amongst other sections. Sometimes, " +"the section exists, but has a name such as *Background* or *Other notes* " +"or *Key topics* - these names are not always useful." +msgstr "" + +#: ../../explanation.rst:22 637227b03e3146888da33db76ad240c0 +msgid "" +"Explanation is less easy to create than it might seem - things that are " +"straightforward to explain when you have the starting-point of someone’s " +"question are less easy when you have a blank page and have to write down " +"something about it." +msgstr "" + +#: ../../explanation.rst:24 5c660edcd4b244529af4bc73eef4b07c +msgid "" +"A topic isn’t defined by a specific task you want to achieve, like a how-" +"to guide, or what you want the user to learn, like a tutorial. It’s not " +"defined by a piece of the machinery, like reference material. It’s " +"defined by what **you** think is a reasonable area to try to cover at one" +" time, so the division of topics for discussion can sometimes be a little" +" arbitrary." +msgstr "" + +#: ../../explanation.rst:29 b538c1bfda3e41c68e8ebb3642729ee9 +msgid "Analogy from cooking" +msgstr "" + +#: ../../explanation.rst:36 1f133d9c887541a5865715ada18ee8a2 +msgid "" +"Think about a work that discusses food and cooking in the context of " +"history, science and technology. It's *about* cooking and the kitchen." +msgstr "" + +#: ../../explanation.rst:39 bf838bbd8e994720b68225069671fcae +msgid "" +"It doesn't teach, it's not a collection of recipes, and it doesn't just " +"describe." +msgstr "" + +#: ../../explanation.rst:41 83ba447031074007bcba5f111022d1a2 +msgid "" +"Instead, it analyses, considers things from multiple perspectives. It " +"might explain why it is we now do things the way we do, or even describe " +"bad ways of doing things, or obscure alternatives." +msgstr "" + +#: ../../explanation.rst:44 c32018253eb649c89f8b8fcacf256204 +msgid "" +"It deepens our knowledge and makes it richer, even if it isn't knowledge " +"we can actually apply in any practical sense - but it doesn't need to be," +" in order to be valuable." +msgstr "" + +#: ../../explanation.rst:46 9ed344f090ec4e639e20a7414fa9d7a7 +msgid "" +"It's something we might read at our leisure, away from the kitchen " +"itself, when we want to think about cooking at a higher level, and to " +"understand more about the subject." +msgstr "" + +#: ../../explanation.rst:52 e960f9602f6a402a87f23f50a1273f6f +msgid "How to write a good explanation" +msgstr "" + +#: ../../explanation.rst:56 16f8637506a946c5b04928f680ec8dcc +msgid "the bigger picture" +msgstr "" + +#: ../../explanation.rst:57 3f286f1efb1c44dab91dcf75bb88f41d +msgid "history" +msgstr "" + +#: ../../explanation.rst:58 f3f99f836fb048839a430586b8c149be +msgid "choices, alternatives, possibilities" +msgstr "" + +#: ../../explanation.rst:59 2f1dbb945c6f4b31b70a3cb02732b7a1 +msgid "why: reasons and justifications" +msgstr "" + +#: ../../explanation.rst:62 21feac9f04a84fba9dfbc2c9559b4b90 +msgid "Provide context" +msgstr "" + +#: ../../explanation.rst:64 7caf0734f9184d81b52772c1d63c555f +msgid "" +"**Explanations are the place for background and context** - for example, " +"*Web forms and how they are handled in Django*, or *Search in django " +"CMS*." +msgstr "" + +#: ../../explanation.rst:66 3c6688306eeb4aa6b3c9531ebe973d29 +msgid "" +"They can also explain *why* things are so - design decisions, historical " +"reasons, technical constraints." +msgstr "" + +#: ../../explanation.rst:70 032e4b97802f44f89d1a38058d8162e3 +msgid "Discuss alternatives and opinions" +msgstr "" + +#: ../../explanation.rst:72 27d4e11fe1e1457cb0d63010e22297cb +msgid "" +"**Explanation can consider alternatives**, or multiple different " +"approaches to the same question. For example, in an article on Django " +"deployment, it would be appropriate to consider and evaluate different " +"web server options," +msgstr "" + +#: ../../explanation.rst:74 2f2091c86360444ca30403662fb9ee5a +msgid "" +"Discussions can even consider and weigh up contrary *opinions* - for " +"example, whether test modules should be in a package directory, or not." +msgstr "" + +#: ../../explanation.rst:78 088ce4d257f7487d849e1d4f27b172b3 +msgid "Don't instruct, or provide technical reference" +msgstr "" + +#: ../../explanation.rst:80 dceb0aaaa1b64bdba694da108abcd6d1 +msgid "" +"**Explanation should do things that the other parts of the documentation " +"do not.** It’s not the place of an explanation to instruct the user in " +"how to do something. Nor should it provide technical description. These " +"functions of documentation are already taken care of in other sections." +msgstr "" + +#: ../../explanation.rst:85 4f01f0b9190f4260b45ac92785f5d410 +msgid "The language of explanation" +msgstr "" + +#: ../../explanation.rst:87 b907c3ea7f524db8a032080795c11dbb +msgid "*The reason for x is because historically, y...*" +msgstr "" + +#: ../../explanation.rst:88 24785388a25245feb71cb4de6c987c34 +msgid "Explain." +msgstr "" + +#: ../../explanation.rst:89 4ab3dce5190b418da2a4771ef55b67ef +msgid "*W is better than z, because...*" +msgstr "" + +#: ../../explanation.rst:90 337ec1c02d8946b4a0dd734c6b92e3aa +msgid "Offer judgements and even opinions where appropriate.." +msgstr "" + +#: ../../explanation.rst:91 1a4f9fe4098d4482845408710a4f29af +msgid "*An x in system y is analogous to a w in system z. However...*" +msgstr "" + +#: ../../explanation.rst:92 4cd5400147fc46c3a0fd5ccc9a1d7272 +msgid "Provide context that helps the reader." +msgstr "" + +#: ../../explanation.rst:93 dc0adcef6cc64f8bbf86df6b71344a4f +msgid "*Some users prefer w (because z). This can be a good approach, but...*" +msgstr "" + +#: ../../explanation.rst:94 faec3637cd454a02b0c0edca0b669047 +msgid "Weigh up alternatives." +msgstr "" + +#: ../../explanation.rst:96 5463962930464a52adc9c3709b14223b +msgid "*An x interacts with a y as follows:...*" +msgstr "" + +#: ../../explanation.rst:96 e2beceaa5bd743be8e602b83f76b0580 +msgid "" +"Unfold the machinery's internal secrets, to help understand why something" +" does what it does." +msgstr "" + +#: ../../explanation.rst:101 27cd38717154499296199cb629f7958e +msgid "Example from Divio's documentation" +msgstr "" + +#: ../../explanation.rst:103 9db7029a9a0047c09734557f9166ecb1 +msgid "" +"Have a look at `our explanation section " +"`_ (titled " +"\"Background\" - the name is not important as long as the purpose is " +"clear)." +msgstr "" + +#: ../../explanation.rst:111 2c0bfb05d9cc4e15a5b40ab808a92ffc +msgid "" +"These articles don’t teach anything. They don’t tell the user what to do." +" They aren’t reference guides. They just discuss particular topics. The " +"user doesn’t *need* to know about (for example) caching or CDN or how we " +"manage environment variables in order to use the platform or achieve any " +"particular task, but the time is likely to come when someone's experience" +" and use of the platform will be improved by having a clearer, better, " +"deeper understanding of those things." +msgstr "" + +#: ../../explanation.rst:117 e5ae9614c6fc4a6f8521bb912c5d2e60 +msgid "" +"These articles provide the bigger picture, the context. Users are human " +"beings; maybe they don’t strictly need to know why we do a certain thing " +"a certain way, but knowing it might well provide them with a kind of " +"satisfaction and comfort that makes them a happier user of the product." +msgstr "" + diff --git a/locales/pt_BR/LC_MESSAGES/how-to-guides.mo b/locales/pt_BR/LC_MESSAGES/how-to-guides.mo new file mode 100644 index 0000000..ca332d3 Binary files /dev/null and b/locales/pt_BR/LC_MESSAGES/how-to-guides.mo differ diff --git a/locales/pt_BR/LC_MESSAGES/how-to-guides.po b/locales/pt_BR/LC_MESSAGES/how-to-guides.po new file mode 100644 index 0000000..acccc49 --- /dev/null +++ b/locales/pt_BR/LC_MESSAGES/how-to-guides.po @@ -0,0 +1,262 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2017-2021, Daniele Procida +# This file is distributed under the same license as the Diátaxis package. +# FIRST AUTHOR , 2021. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Diátaxis \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2021-04-18 20:02-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.9.0\n" + +#: ../../how-to-guides.rst:4 10a14d93cd464b9cbd59ef1a4871beb7 +msgid "About how-to guides" +msgstr "" + +#: ../../how-to-guides.rst:8 af68aee6bdb14856acc4862183de4c2f +msgid "" +"How-to guides are **directions** that take the reader through the steps " +"required to solve a real-world problem. How-to guides are **goal-" +"oriented**." +msgstr "" + +#: ../../how-to-guides.rst:11 3dd622072bcf48d29f4436cea607a1c1 +msgid "" +"How-to guides are recipes, directions to achieve a specific end - for " +"example: *how to create a web form*; *how to plot a three-dimensional " +"data-set*; *how to enable LDAP authentication*." +msgstr "" + +#: ../../how-to-guides.rst:18 f42c4b43aae64b02a24488a1fa1f26aa +msgid "" +"**How-to guides are wholly distinct from tutorials** and must not be " +"confused with them:" +msgstr "" + +#: ../../how-to-guides.rst:20 5234a0d3080548b99d29a5e271ec8fbb +msgid "A tutorial is what you decide a beginner needs to know." +msgstr "" + +#: ../../how-to-guides.rst:21 7f61e606d8294bd7ac7acf7a11d99055 +msgid "" +"A how-to guide is an answer to a question that only a user with some " +"experience could even formulate." +msgstr "" + +#: ../../how-to-guides.rst:23 442b2b0894ba443cbc1d5c04729301da +msgid "" +"In a how-to guide, you can assume some knowledge and understanding. You " +"can assume that the user already knows how to do basic things and use " +"basic tools." +msgstr "" + +#: ../../how-to-guides.rst:25 b2c037f236a945d88ba39fef25c1772c +msgid "" +"Unlike tutorials, how-to guides in software documentation tend to be done" +" fairly well. They’re also fun and easy to write." +msgstr "" + +#: ../../how-to-guides.rst:30 b15b3d399bd24ec0a96bbc2fc8f3b46d +msgid "Analogy from cooking" +msgstr "" + +#: ../../how-to-guides.rst:36 57d74d5a400c44eb8b805ae88cb9518b +msgid "Think about a recipe, for preparing something to eat." +msgstr "" + +#: ../../how-to-guides.rst:38 9ee9e85933164bf8b09e724307083d09 +msgid "" +"A recipe has a clear, defined end. It addresses a specific question. It " +"shows someone - who can be assumed to have some basic knowledge already -" +" how to achieve something." +msgstr "" + +#: ../../how-to-guides.rst:40 41bb9d35f3f24ba8893640bfdaa66984 +msgid "" +"Someone who has never cooked before can't be expected to follow a recipe " +"with success, so a recipe is not a substitute for a cooking lesson. At " +"the same time, someone who reads a recipe would be irritated to find that" +" it tries to teach basics that they know already, or contains irrelevant " +"discussion of the ingredients." +msgstr "" + +#: ../../how-to-guides.rst:46 965851d3e9614e0782c5ba37a44bf1c4 +msgid "How to write good how-to guides" +msgstr "" + +#: ../../how-to-guides.rst:50 e1fd423598bf44d6baf16c2d655eddd0 +msgid "focused on tasks or problems" +msgstr "" + +#: ../../how-to-guides.rst:51 71d9db0ef8dc4413965e87bdcd2355c0 +msgid "assume the user knows what they want to achieve" +msgstr "" + +#: ../../how-to-guides.rst:52 c015dc3960054ed69f2ed39b1816df38 +msgid "action and only action" +msgstr "" + +#: ../../how-to-guides.rst:53 1a71ed3b36ab487c8379c1ebe196f18b +msgid "no digression, explanation, teaching" +msgstr "" + +#: ../../how-to-guides.rst:56 f6e39a51b01e41b7b814a7ce6f930cba +msgid "Provide a series of steps" +msgstr "" + +#: ../../how-to-guides.rst:58 8651601a76dd4d6498b624dfd088902d +msgid "" +"**How-to guides must contain a list of steps, that need to be followed in" +" order** (just like tutorials do). You don’t have to start at the very " +"beginning, just at a reasonable starting point. How-to guides should be " +"reliable, but they don’t need to have the cast-iron repeatability of a " +"tutorial." +msgstr "" + +#: ../../how-to-guides.rst:62 f68767aa47fb4970b8d9c1a96627eed2 +msgid "Focus on results" +msgstr "" + +#: ../../how-to-guides.rst:64 63e333645ca84bc586d0515e43f7ebaf +msgid "" +"**How-to guides must focus on achieving a practical goal.** Anything else" +" is a distraction. As in tutorials, detailed explanations are out of " +"place here." +msgstr "" + +#: ../../how-to-guides.rst:68 dc6a53ae78ab49b0a639f90bafd9be7f +msgid "Solve a particular problem" +msgstr "" + +#: ../../how-to-guides.rst:70 1341da78b1394d9aac44f2d6bbfbb5ef +msgid "" +"**A how-to guide must address a specific question or problem**: *How do I" +" …?*" +msgstr "" + +#: ../../how-to-guides.rst:72 35d5d22f21734830aa5686832ec403e4 +msgid "" +"This is one way in which how-to guides are distinct from tutorials: when " +"it comes to a how-to guide, the reader can be assumed to know *what* they" +" should achieve, but don’t yet know *how* - whereas in the tutorial, " +"*you* are responsible for deciding what things the reader needs to know " +"about." +msgstr "" + +#: ../../how-to-guides.rst:76 a0590f0c31c148a0a947bbf9608b5638 +msgid "Don't explain concepts" +msgstr "" + +#: ../../how-to-guides.rst:78 475331119fab4b21ae7589696d152e11 +msgid "" +"**A how-to guide should not explain things.** It’s not the place for " +"discussions of that kind; they will simply get in the way of the action. " +"If explanations are important, link to them." +msgstr "" + +#: ../../how-to-guides.rst:82 d98fff99978d4f339390bd89f74140a1 +msgid "Allow for some flexibility" +msgstr "" + +#: ../../how-to-guides.rst:84 9ed204ad0f9a4b7e9c33e2cbc765b346 +msgid "" +"**A how-to guide should allow for slightly different ways of doing the " +"same thing.** It needs just enough flexibility in it that the user can " +"see how it will apply to slightly different examples from the one you " +"describe, or understand how to adapt it to a slightly different system or" +" configuration from the one you’re assuming. Don’t be so specific that " +"the guide is useless for anything except the exact purpose you have in " +"mind." +msgstr "" + +#: ../../how-to-guides.rst:88 f0613f24a76749e595d7ffb2744ad187 +msgid "Leave things out" +msgstr "" + +#: ../../how-to-guides.rst:90 3a0ae3f3f3ce44b3b6d7e1dcf8e8a20c +msgid "" +"**Practical usability is more valuable than completeness.** Tutorials " +"need to be complete, end-to-end guides; how-to guides do not. They can " +"start and end where it seems appropriate to you. They don’t need to " +"mention everything that there is to mention either, just because it is " +"related to the topic. A bloated how-to guide doesn’t help the user get " +"speedily to their solution." +msgstr "" + +#: ../../how-to-guides.rst:94 528a4193ab7d46c6b94e3ef560f7fbf7 +msgid "Name guides well" +msgstr "" + +#: ../../how-to-guides.rst:96 f736688f33e04f33aec94561e40802e7 +msgid "" +"**The title of a how-to document should tell the user exactly what it " +"does.** *How to create a class-based view* is a good title. *Creating a " +"class-based view* or worse, *Class-based views*, are not." +msgstr "" + +#: ../../how-to-guides.rst:101 b2cb95431d1e4ae2b8f625edba42481c +msgid "The language of how-to guides" +msgstr "" + +#: ../../how-to-guides.rst:103 217bd89f38e449afa6c45452835eaab3 +msgid "*This guide shows you how to...*" +msgstr "" + +#: ../../how-to-guides.rst:104 30f400d9d5dd4627a1e4d3e82cd4598f +msgid "" +"Describe clearly the problem or task that the guide shows the user how to" +" solve." +msgstr "" + +#: ../../how-to-guides.rst:105 8f5617072f7b41dd9c6c1828be8bef12 +msgid "*If you want x, do y. To achieve w, do z.*" +msgstr "" + +#: ../../how-to-guides.rst:106 27d289b096414738a49d6d3cb495272f +msgid "Use conditional imperatives." +msgstr "" + +#: ../../how-to-guides.rst:108 50f24ccdc8494b11a4f223d5cf38cf69 +msgid "*Refer to the x reference guide for a full list of options.*" +msgstr "" + +#: ../../how-to-guides.rst:108 939ac270a0ed4e9594e0300eab914473 +msgid "" +"Don't pollute your practical how-to guide with every possible thing the " +"user might do related to x." +msgstr "" + +#: ../../how-to-guides.rst:113 4ad5b71430c7402a8b27b7384b12b8c4 +msgid "Example from Divio's documentation" +msgstr "" + +#: ../../how-to-guides.rst:115 ed09ed1708d744a58d7eccd72332ed07 +msgid "" +"Have a look at `our how-to guides `_." +msgstr "" + +#: ../../how-to-guides.rst:122 5d86b6ee09cd4ff9bec49165112c839e +msgid "" +"Each one of these is an answer to a question, or problem: *how do I...?* " +"Each title can clearly be preceded by the words “How to”. Each one is a " +"recipe, that takes you through the steps required to complete a specific " +"task." +msgstr "" + +#: ../../how-to-guides.rst:125 fb0319cfc5a34942aeab7f8a5a53dd74 +msgid "" +"Although both the tutorials and the how-to guides serve the needs of the " +"user, the tutorials are led by the author who knows what the user needs " +"to know, while the how-to guides are led by the user who asks the " +"questions." +msgstr "" + diff --git a/locales/pt_BR/LC_MESSAGES/index.mo b/locales/pt_BR/LC_MESSAGES/index.mo new file mode 100644 index 0000000..af16ee0 Binary files /dev/null and b/locales/pt_BR/LC_MESSAGES/index.mo differ diff --git a/locales/pt_BR/LC_MESSAGES/index.po b/locales/pt_BR/LC_MESSAGES/index.po new file mode 100644 index 0000000..e5dfba3 --- /dev/null +++ b/locales/pt_BR/LC_MESSAGES/index.po @@ -0,0 +1,169 @@ +# DIÁTAXIS FRAMEWORK. BRAZILIAN PORTUGUESE TRANSLATION. +# Copyright (C) 2017-2021, Daniele Procida +# This file is distributed under the same license as the Diátaxis package. +# SeuPedro , 2021. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Diátaxis \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2021-04-18 20:02-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: SeuPedro \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.9.0\n" + +#: ../../index.rst:78 +msgid "Home" +msgstr "Início" + +#: ../../index.rst:1 5d4dc298cecf461880770574228c213c +msgid "" +"The Diátaxis framework solves the problem of structure in technical " +"documentation, making it easier to create, maintain and use." +msgstr "" +"O framework Diátaxis resolve o problema de como estrutuar documentação técnica, " +"fazendo com que seja fácil de manter e de usar." + +#: ../../index.rst:1 6507c55426a04475951babe7e253a8f7 +msgid "documentation, four, kinds" +msgstr "documentação, quatro, tipos" + +#: ../../index.rst:9 b826969db88244f7a8a9d0836e666091 +msgid "Diátaxis Framework" +msgstr "Framework Diátaxis" + +#: ../../index.rst:12 e934190d8445400f96e55a5b976af2a8 +msgid "A systematic framework for technical documentation authoring." +msgstr "Um framework sistemático para autoria de documentação técnica." + +#: ../../index.rst:13 19cb053aa5b2468aa7ef9af3b15cd0be +msgid "" +"The Diátaxis framework aims to solve the problem of structure in " +"technical documentation. It adopts a systematic approach to understanding" +" the needs of documentation users in their cycle of interaction with a " +"product." +msgstr "" +"O framework Diátaxis tem como objeto resolver o problema de estrutura em " +"documentações técnicas. Ele adota uma abordagem sistemática para entender " +"a necessidade dos usuários de documentação em seus ciclos de interação com um " +"produto." + +#: ../../index.rst:20 0ca4e182ca474dd09273a5a17fc5d10c +msgid "The Grand Unified Theory of Documentation" +msgstr "A Grande Teoria Unificada de Documentação" + +#: ../../index.rst:24 df6a3d7722b94bdc8b8bada0672fd09d +msgid "\\- David Laing" +msgstr "" + +#: 7ad5baed5652434e9be1be98f092c858 +msgid "*Diátaxis*" +msgstr "" + +#: ../../index.rst:31 3211aa56714543fcacf80cde25671c59 +msgid "" +"From the Ancient Greek δῐᾰ́τᾰξῐς - *dia*, \"across\", and *taxis*, " +"\"arrangement\"." +msgstr "" +"Do Grego Antigo δῐᾰ́τᾰξῐς - *dia*, \"através\", e *taxis*, " +"\"arranjo\"." + +#: ../../index.rst:33 537737026d7e445ab645c54103db2225 +msgid "" +"The framework identifies four modes of documentation - **tutorials**, " +"**how-to guides**, **technical reference** and **explanation**." +msgstr "" +"O framework identifica quatro modos de documentação - **tutoriais**, " +"**guias de como-fazer**, **referência técnica** e **explanação**." + +#: ../../index.rst:36 cec90d3849eb4cf18d185672af49342e +msgid "" +"Each of these modes (or types) answers to a different user need, fulfils " +"a different purpose and requires a different approach to its creation." +msgstr "" +"Cada um desses modos (ou tipos) corresponde a uma necessidade diferente do usuário, cumpre " +"uma finalidade diferente e requer uma abordagem diferente para sua criação." + +#: ../../index.rst:42 f04f1ccf4221449e9ee630988a31830d +msgid "" +"In other words, what we call *documentation* is fundamentally not one " +"thing, but four. Understanding the implications of this will help improve" +" most documentation - often immensely." +msgstr "" +"Em outras palavras, o que nós chamamos *documentação* não é fundamentalmente uma " +"coisa só, mas quatro. Compreender essas implicações vai ajudar a melhorar " +"bastante a documentação - muitas vezes imensamente." + +#: ../../index.rst:46 d8155a4fe0f54456860e7854a55b182a +msgid "" +"Diátaxis promises to make documentation and projects better, and the " +"teams that work with them more successful." +msgstr "" +"Diátaxis promete tornar documentação e projetos melhores, e as " +"equipes com quem trabalham mais bem sucedidas." + +#: ../../index.rst:52 d65e055aa0f2477683047e0cef6b462d +msgid "" +"While redesigning the `Cloudflare developer docs " +"`_, this content framework became our " +"north star for information architecture. When we weren’t sure where a new" +" piece of content should fit in, we’d consult the framework. Our " +"documentation is now clearer than it’s ever been, both for readers and " +"contributors." +msgstr "" +"Quando estávamos redesenhando a `documentação para desenvolvedores da Clouflare " +"`_, o conteúdo desse framework se tornou nosso " +"norte para estruturar a informação. Quando nós não tínhamos certeza sobre aonde um novo " +"pedaço de conteúdo deveria se encaixar, nós consultamos o framework. Agora nossa " +"documentação está mais clara do que nunca, tanto para os leitores quando para os " +"colaboradores." + + +#: ../../index.rst:59 fb33b7b8253b4d5fa22f090b1f429167 +msgid "\\- Adam Schwartz (`@AdamSchwartz `_)" +msgstr "" + +#: ../../index.rst:64 b60bf7c948fd47fc94ca4686b0336a6c +msgid "Light-weight and easily adopted" +msgstr "Leve e de fácil adoção" + +#: ../../index.rst:66 b39e8b3023ee4ae5a4eafc938a61c716 +msgid "" +"The framework is light-weight, easy to understand and straightforward to " +"apply. It doesn't impose implementation constraints." +msgstr "" +"O framework é leve, fácil de entender e simples de " +"aplicar. Ele não impõe restrições de implementação." + +#: ../../index.rst:70 5e7eec8eecbe4490bc7c0d3ff4109bea +msgid "Complete and comprehensive" +msgstr "Completo e abrangente" + +#: ../../index.rst:72 90b67ace26b940ce82ccc12c04b9a28e +msgid "" +"Diátaxis provides a comprehensive and nearly universally-applicable " +"scheme, that has been :ref:`proven in practice across a wide variety of " +"fields and applications `. These include large and small, and " +"open and proprietary documentation projects." +msgstr "" +"Diátaxis fornece um esquema abrangente e quase universalmente-aplicável, " +"que tem sido :ref:`testado na prática através de uma grande variedade de " +"adoção de aplicações e campos `. Entre os quais inclui projetos de documentação grandes, pequenos, " +"abertos ou proprietários." + +#: ../../index.rst:94 8289b2e94ef04fc3826bb9b43092f452 +msgid "Video presentation" +msgstr "Apresentação em vídeo" + +#: ../../index.rst:96 8db615563288493a9b6585b760345572 +msgid "" +"If you'd prefer to watch a video covering this topic, here is it " +"(courtesy of PyCon Australia 2017)." +msgstr "" +"Se preferir assistir a um video que explica sobre esse tópico, aqui está " +"(cortesia de PyCon Australia 2017)." diff --git a/locales/pt_BR/LC_MESSAGES/introduction.mo b/locales/pt_BR/LC_MESSAGES/introduction.mo new file mode 100644 index 0000000..766c4c5 Binary files /dev/null and b/locales/pt_BR/LC_MESSAGES/introduction.mo differ diff --git a/locales/pt_BR/LC_MESSAGES/introduction.po b/locales/pt_BR/LC_MESSAGES/introduction.po new file mode 100644 index 0000000..892f063 --- /dev/null +++ b/locales/pt_BR/LC_MESSAGES/introduction.po @@ -0,0 +1,318 @@ +# DIÁTAXIS FRAMEWORK. BRAZILIAN PORTUGUESE TRANSLATION. +# Copyright (C) 2017-2021, Daniele Procida +# This file is distributed under the same license as the Diátaxis package. +# SeuPedro , 2021. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Diátaxis \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2021-04-18 20:02-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: SeuPedro \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.9.0\n" + +#: ../../introduction.rst:10 5d275717c1ca4563b7056ce2544b66f9 +msgid "Introduction" +msgstr "Introdução" + +#: ../../introduction.rst:13 b812b49edb544263a1edcab8ed983d3d +msgid "The problem and the solution" +msgstr "O problema e a solução" + +#: ../../introduction.rst:16 a827233c3f524fd5a3758122081437e0 +msgid "The problem it solves" +msgstr "O problema que resolve" + +#: ../../introduction.rst:18 40eadc22c74849938afeb56b67530601 +msgid "" +"It doesn’t matter how good your product is, because **if its " +"documentation is not good enough, people will not use it**. Even if they" +" have to use it because they have no choice, without good documentation, " +"they won’t use it effectively or the way you’d like them to." +msgstr "" +"Não importa o quão bom seja produto, **se a documentação " +"dele não for boa o suficiente, as pessoas não vão usar**. Mesmo se elas " +"sejam obrigadas a usar por não terem escolha, sem uma boa documentação, " +"elas não vão usar de um modo efetivo ou do jeito que gostariam que fosse." + +#: ../../introduction.rst:21 6fbb11c37425418dbb85f3931b4a7396 +msgid "" +"Nearly everyone understands this. Nearly everyone knows that they need " +"good documentation, and **most people try to create good documentation**." +" And **most people fail**." +msgstr "" +"Quase todo mundo sabe isso. Quase todo mundo entende que precisa de " +"uma boa documentação, e **a maioria das pessoas tentam criar uma boa documentação**. " +"**Mas a grande parte falha**." + +#: ../../introduction.rst:23 b73090018f6644e5919b0236c284c7da +msgid "" +"Usually, it’s not because they don’t try hard enough. Usually, it’s " +"because they are not doing it the right way." +msgstr "" +"Normalmente, não é por que não se esforçaram o bastante. Mas " +"por que não estão fazendo da maneira correta." + +#: ../../introduction.rst:25 719431e9f10a4f0dada6a238f13b85c0 +msgid "" +"This system is a way to make your documentation better, not by working " +"harder at it, but by doing it the right way. **The right way is the " +"easier way** - easier to write, and easier to maintain." +msgstr "" +"Esse sistema é uma forma de melhorar a documentação, não por trabalhar " +"pegando pesado, mas por fazer da forma certa. **A forma certa é o jeito " +"mais fácil** - fácil de escrever e fácil de manter." + +#: ../../introduction.rst:29 53684c3da98f4f9ba16539272dd94bef +msgid "The 'secret'" +msgstr "O 'segredo'" + +#: ../../introduction.rst:31 b4713c34e0ef4f0594cdec4233aed6d3 +msgid "" +"It's not actually a secret and it certainly shouldn't be: documentation " +"needs to include and be structured around its **four different " +"functions**: *tutorials*, *how-to guides*, *technical reference* and " +"*explanation*. Each of them **requires a distinct mode of writing**. " +"People working with software need these four different kinds of " +"documentation at different times, in different circumstances - so " +"software usually needs them all, and they should all be integrated into " +"your documentation." +msgstr "" +"Na verdade, não é nenhum segredo e nem deveria ser: a documentação " +"precisa incluir e ser estruturada em torno de **quatro pilares " +"diferentes**: *tutoriais*, *guias de como-fazer*, *referência técnica* e " +"*explanação*. Cada uma delas **requer uma forma distinta de escrever**. " +"Pessoas que trabalham com programação precisam desses quatro tipos diferentes de " +"documentação em diferentes momentos, e em diferentes circustâncias - e como " +"na área de programação geralmente se precisa de todos os quatro pilares, todos eles precisam estar integrados na " +"sua documentação." + +#: ../../introduction.rst:33 0d5282426b524b2b9a7d426ddb41d356 +msgid "" +"And documentation needs to be explicitly structured around them, and they" +" all must be kept separate and distinct from each other." +msgstr "" +"E a documentação precisa estar explicitamente organizada em torno desses quatro, e todos eles " +"precisam ser mantidos separados e distintos uma dos outros." + +#: ../../introduction.rst:42 a1e3482eb66447b08b71d7e3a0900691 +msgid "\\" +msgstr "" + +#: ../../introduction.rst:43 46397dd4e4d34d1c9b52f07d9c301321 +msgid ":ref:`Tutorials `" +msgstr ":ref:`Tutoriais `" + +#: ../../introduction.rst:44 6eed94c51433444a919c0ea32492bed6 +msgid ":ref:`How-to guides `" +msgstr ":ref:`Guias de como-fazer `" + +#: ../../introduction.rst:45 8a9b40e16d894fcea9630cb45c6f4b9c +msgid ":ref:`Reference `" +msgstr ":ref:`Referência `" + +#: ../../introduction.rst:46 506331d1b11147879ac562a9d29f2a43 +msgid ":ref:`Explanation `" +msgstr ":ref:`Explanação `" + +#: ../../introduction.rst:47 0216bad56246429881712c42507ca7c0 +msgid "*oriented to*" +msgstr "*orientado a*" + +#: ../../introduction.rst:48 bce3440835184eb5b5cc6eb492900c97 +msgid "learning" +msgstr "aprendizado" + +#: ../../introduction.rst:49 831cf4c5dd4d44cea3347d3b34ea49b1 +msgid "a goal" +msgstr "um objetivo" + +#: ../../introduction.rst:50 b832e1d7133e467cb60e343ed183273f +msgid "information" +msgstr "informação" + +#: ../../introduction.rst:51 150dde8cb48f48559751ee2985cb7e02 +msgid "understanding" +msgstr "entendimento" + +#: ../../introduction.rst:52 0600f6a3bfbd4c74bd65db76a7593a24 +msgid "*must*" +msgstr "*deve*" + +#: ../../introduction.rst:53 f8fd4cfa2bab492784fa29ab787a02fd +msgid "allow the newcomer to get started" +msgstr "permite que o novato comece" + +#: ../../introduction.rst:54 82b01574d4c945eea8173077c85d7b9d +msgid "show how to solve a specific problem" +msgstr "mostra como resolver um problema específico" + +#: ../../introduction.rst:55 34854317736344e5ac975d6aea50d35c +msgid "describe the machinery" +msgstr "descreve o maquinário" + +#: ../../introduction.rst:56 6614e1cb3b3545b38370ff43de097064 +msgid "explain" +msgstr "explica" + +#: ../../introduction.rst:57 4365ad6678134f9f8e26c908622866c0 +msgid "*its form*" +msgstr "*de qual forma*" + +#: ../../introduction.rst:58 3ed86c11d1734745b3987335c11fc21f +msgid "a lesson" +msgstr "uma lição" + +#: ../../introduction.rst:59 88dc97a3e434430dbc6dd69e0f217252 +msgid "a series of steps" +msgstr "uma série de passos" + +#: ../../introduction.rst:60 a58946191860417889d63d1b39c486c0 +msgid "dry description" +msgstr "descrição direta" + +#: ../../introduction.rst:61 27c15250d91e423dac0b220f09323f0d +msgid "discursive explanation" +msgstr "explicação discursiva" + +#: ../../introduction.rst:62 bfab7a8bb78f4e3399d8a7b59fb2b866 +msgid "*analogy*" +msgstr "*analogia*" + +#: ../../introduction.rst:63 486b9628507344eb91701f92c6acbb48 +msgid "teaching a small child how to cook" +msgstr "ensinar uma criança a cozinhar" + +#: ../../introduction.rst:64 316c551c03c740d8b8f47c837fa495a6 +msgid "a recipe in a cookery book" +msgstr "uma receita de um livro de receitas" + +#: ../../introduction.rst:65 932c077b47e2475682acd725a49371e0 +msgid "a reference encyclopaedia article" +msgstr "uma referência de um artigo de enciclopédia" + +#: ../../introduction.rst:66 2dfdfa7e3db54656a9de191bda554398 +msgid "an article on culinary social history" +msgstr "um artigo sobre história social de culinária" + +#: ../../introduction.rst:68 d91eff690cc6431b9fb604b5e46aa538 +msgid "" +"This division makes it obvious to both author and reader what material, " +"and what *kind* of material, goes where. It tells the author **how to " +"write**, and **what to write**, and **where to write it**. It saves the " +"author from wasting a great deal of time trying to wrestle the " +"information they want to impart into a shape that makes sense, because " +"**each of these kinds of documentation has only one job**." +msgstr "" +"Essa divisão faz com que seja nítido para o autor e para o leitor qual, " +"que *tipo*, e aonde o conteúdo vai. Mostra para o autor **o quê**, " +"**onde** e **como escrever**. Isso evita que o autor " +"perca muito tempo tentando transformar as informações que deseja transmitir " +"em uma forma que faça sentido, porque **cada um desses tipos de documentação tem apenas uma tarefa**." + +#: ../../introduction.rst:75 cde43ac3475144099f3f196becde2615 +msgid "" +"In fact, it’s extremely hard to maintain good documentation that doesn’t " +"implicitly or explicitly recognise the quadrants of this scheme. The " +"demands of each kind are different from those of the others, so **any " +"attempt at documentation that fails to maintain this structure suffers**," +" as it’s pulled in different directions at once." +msgstr "" +"Na verdade, é extremamente difícil manter uma boa documentação que não " +"reconheça de forma implícita ou explicita os quadrantes desse esquema. As " +"demandas de cada tipo são diferentes das outras, então **qualquer " +"tentativa de documentação que falhe em manter essa estrutura sofre**, " +"já que é puxado para diferentes direções ao mesmo tempo. " + +#: ../../introduction.rst:77 4ffca9f5d12242e9816044158f0454d0 +msgid "" +"Once you understand the structure, it becomes a very useful tool for " +"analysing existing documentation, and understanding what needs to be done" +" to improve it." +msgstr "" +"Depois de entender essa estrutura, ela se torna uma ferramenta " +"muito útil para analisar uma documentação existente e entender o que precisa ser feito " +"para melhorá-la." + +#: ../../introduction.rst:79 5ab0c75af7534d77bc0f85e3de11a901 +msgid "" +"In the following sections, each of these four parts is dealt with in " +"detail." +msgstr "" +"Nas seções a seguir, cada uma dessas quatro partes é tratada em" +"detalhe." + +#: ../../introduction.rst:85 5eb401fc24514bbf88e12a9818544812 +msgid "Making documentation work" +msgstr "Fazendo a documentação funcionar" + +#: ../../introduction.rst:88 7f03b9f038504166b849b66eb45e8491 +msgid "For authors" +msgstr "Para os autores" + +#: ../../introduction.rst:90 9ea92352c8784e16b37fc09b0c94b4aa +msgid "" +"One of the biggest headaches that documentation maintainers have to deal " +"with is not having a clear picture of what they should be doing. They " +"write and rewrite, but find it hard to make it fit together in " +"satisfactory ways." +msgstr "" +"Uma das maiores dores de cabeça com que os mantenedores de documentação tem que lidar " +"é não ter uma imagem clara do que deveriam estar fazendo. Eles " +"escrevem e reescrevem, mas acham difícil fazer com que tudo se encaixe de " +"maneira satisfatória." + +#: ../../introduction.rst:92 b315ab4e02514c34810465a198f9202e +msgid "" +"This structure resolves those questions by making clear distinctions and " +"separations. They make documentation that is easier to write and " +"maintain, that’s easier to use and to find one's way around in." +msgstr "" +"Essa estrutura resolve essas questões, fazendo distinções e " +"separações claras. Eles fazem com que a documentação seja mais fácil de escrever e " +"de manter, e que seja mais fácil de usar e de se naveragar por ela." + +#: ../../introduction.rst:94 6a69e62138854cffb123e73488fd90f5 +msgid "" +"The documentation doesn’t write itself - but it’s now possible to write " +"it without also having to wrestle with poor fit, or unclear scope or " +"doubt about what should be included or what style to adopt. It becomes " +"much clearer what to write, how to write it, and where to put it." +msgstr "" +"A documentação não se escreve sozinha - mas agora é possível escrevê-la " +"sem também ter que lutar contra um ajuste inadequado, um escopo pouco claro, " +"uma dúvida sobre o que deve ser incluído ou que estilo adotar. Se torna " +"muito mais claro o que escrever, como escrever e onde colocar as coisas." + +#: ../../introduction.rst:98 389e9ef10fce4559b5d7e85df2aa7b92 +msgid "For readers" +msgstr "Para os leitores" + +#: ../../introduction.rst:100 29dfb76e5e304f059059b500e44329ff +msgid "" +"It serves users better, because for all the different phases in the cycle" +" of their interaction with the software they will find the right kind of " +"documentation, that serves the needs of that moment." +msgstr "" +"Atende melhor os usuários, pois para todas as diferentes fases do ciclo " +"de sua interação com o software eles encontrarão o tipo de documentação certa, " +"que atenda as necessidades daquele momento." + +#: ../../introduction.rst:102 0a22e771b39f42438c643646ef8d1c27 +msgid "" +"Writing documentation that explicitly and distinctly addresses each of " +"the four quadrants helps the software attract and keep more users, who " +"will use it more effectively - and that is one of the things the creators" +" of software want most of all." +msgstr "" +"Escrever uma documentação que trate de forma explícita e distinta cada um " +"dos quatro quadrantes ajuda o software a atrair e manter mais usuários, que " +"o usarão de forma mais eficaz - e isso é uma das coisas que os criadores " +"de software mais desejam." + diff --git a/locales/pt_BR/LC_MESSAGES/reference.mo b/locales/pt_BR/LC_MESSAGES/reference.mo new file mode 100644 index 0000000..ca332d3 Binary files /dev/null and b/locales/pt_BR/LC_MESSAGES/reference.mo differ diff --git a/locales/pt_BR/LC_MESSAGES/reference.po b/locales/pt_BR/LC_MESSAGES/reference.po new file mode 100644 index 0000000..5c6bb7a --- /dev/null +++ b/locales/pt_BR/LC_MESSAGES/reference.po @@ -0,0 +1,236 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2017-2021, Daniele Procida +# This file is distributed under the same license as the Diátaxis package. +# FIRST AUTHOR , 2021. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Diátaxis \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2021-04-18 20:02-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.9.0\n" + +#: ../../reference.rst:4 9dbf9891809946de9f2d7126b1331398 +msgid "About reference" +msgstr "" + +#: ../../reference.rst:8 c60988a1192940ff9a5f525ed4d86da2 +msgid "" +"Reference guides are **technical descriptions** of the machinery and how " +"to operate it. Reference material is **information-oriented**." +msgstr "" + +#: ../../reference.rst:11 408f6e9f52064f6db45ae34d3e3b7979 +msgid "" +"Reference guides have one job only: to describe. They are code-" +"determined, because ultimately that's what they describe: key classes, " +"functions, APIs, and so they should list things like functions, fields, " +"attributes and methods, and set out how to use them." +msgstr "" + +#: ../../reference.rst:18 c168e9cfa2dd4e62bdc67af30f9a5141 +msgid "" +"By all means technical reference can contain examples to illustrate " +"usage, but it should not attempt to explain basic concepts, or how to " +"achieve common tasks." +msgstr "" + +#: ../../reference.rst:20 b78fd7ab67f24c07a6eac058a3ab08b0 +msgid "Reference material should be **austere and to the point**." +msgstr "" + +#: ../../reference.rst:22 f089b278824646979aa806c779b9e3f3 +msgid "" +"Note that description **does** include basic description of how to use " +"the machinery - how to instantiate a particular class, or invoke a " +"certain method, for example, or precautions that must be taken when " +"passing something to a function. However this is simply part of its " +"function as technical reference, and emphatically **not** to be confused " +"with a how-to guide - *describing correct usage of software* (technical " +"reference) is not the same as *showing how to use it to achieve a certain" +" end* (how-to documentation)." +msgstr "" + +#: ../../reference.rst:24 57a2921080a744a58f78c329fd464df7 +msgid "" +"For some developers, reference guides are the only kind of documentation " +"they can imagine. They already understand their software, they know how " +"to use it. All they can imagine that other people might need is technical" +" information about it." +msgstr "" + +#: ../../reference.rst:26 f1b61751d9b54fd9a15a8d16ad8c7ba5 +msgid "" +"Reference material tends to be written well. It can even - to some extent" +" - be generated automatically, but this is never sufficient on its own." +msgstr "" + +#: ../../reference.rst:31 e5894d70d840491ba620d8f2309d8b79 +msgid "Analogy from cooking" +msgstr "" + +#: ../../reference.rst:39 b7f9678e9a0d4f6fa8eb885b1de346c5 +msgid "Consider an encyclopaedia article about an ingredient, say ginger." +msgstr "" + +#: ../../reference.rst:41 aee8e9615bb74ba2a429f4155093ab20 +msgid "" +"When you look up *ginger* in a reference work, what you want is " +"*information* about the ingredient - information describing its " +"provenance, its behaviour, its chemical constituents, how it can be " +"cooked." +msgstr "" + +#: ../../reference.rst:43 1041c8bc1761453a88b0f9390200d792 +msgid "" +"You expect that whatever ingredient you look up, the information will be " +"presented in a similar way. And you expect to be informed of basic facts," +" such as *ginger is a member of the family that includes turmeric and " +"cardamom*." +msgstr "" + +#: ../../reference.rst:46 6396172b776341b78c9c3a6e69752fce +msgid "" +"This is also where you'd expect to be alerted about potential problems, " +"such as: *ginger is known to provoke heartburn in some individuals* or: " +"*ginger may interfere with the effects of anticoagulants, such as " +"warfarin or aspirin*." +msgstr "" + +#: ../../reference.rst:53 c09a1e111a9f43cbbafb730644810975 +msgid "austere and uncompromising" +msgstr "" + +#: ../../reference.rst:54 43f04fabae88405c8740570cfe9fb6ed +msgid "neutrality, objectivity, factuality" +msgstr "" + +#: ../../reference.rst:55 901de1a2b5f244e4af08c17ee0b73062 +msgid "structured according to the structure of the machinery itself" +msgstr "" + +#: ../../reference.rst:58 0249e88dfc714391b06dc85256bda5dc +msgid "How to write good reference guides" +msgstr "" + +#: ../../reference.rst:61 a81664e6b620485e94d2217100f11b7b +msgid "Structure the documentation around the code" +msgstr "" + +#: ../../reference.rst:63 78fdf30cdb414e1b8cddebaaacc44535 +msgid "" +"**Give reference documentation the same structure as the codebase**, so " +"that the user can navigate both the code and the documentation for it at " +"the same time. This will also help the maintainers see where reference " +"documentation is missing or needs to be updated." +msgstr "" + +#: ../../reference.rst:67 89ff7fae4a21416fac3094797dfd5644 +msgid "Be consistent" +msgstr "" + +#: ../../reference.rst:69 aad6e5a0310d46a8a3dcb5fbb4ec48d5 +msgid "" +"**In reference guides, structure, tone, format must all be consistent** -" +" as consistent as those of an encyclopaedia or dictionary." +msgstr "" + +#: ../../reference.rst:73 0e2fbbb959e0455794302a2788c4dde3 +msgid "Do nothing but describe" +msgstr "" + +#: ../../reference.rst:75 a1d3f694648648d09b1bae2e128ae379 +msgid "" +"**The only job of technical reference is to describe**, as clearly and " +"completely as possible. Anything else (explanation, discussion, " +"instruction, speculation, opinion) is not only a distraction, but will " +"make it harder to use and maintain. Provide examples to illustrate the " +"description when appropriate." +msgstr "" + +#: ../../reference.rst:77 b0673a55cc96483b9f6870cd66e00e02 +msgid "" +"Avoid the temptation to use reference material to instruct in how to " +"achieve things, beyond the basic scope of using the software, and don’t " +"allow explanations of concepts or discussions of topics to develop. " +"Instead, link to how-to guides, explanation and introductory tutorials as" +" appropriate." +msgstr "" + +#: ../../reference.rst:81 0a4dca9e3ca54c7f8d107456bbf97d14 +msgid "Be accurate" +msgstr "" + +#: ../../reference.rst:83 e2a1d71e946f475693be27a2f6947884 +msgid "" +"**These descriptions must be accurate and kept up-to-date.** Any " +"discrepancy between the machinery and your description of it will " +"inevitably lead a user astray." +msgstr "" + +#: ../../reference.rst:88 d26c517421174007b7a4ce4925611c55 +msgid "The language of reference guides" +msgstr "" + +#: ../../reference.rst:90 1e7f1680a63b425fae445812745e4bbf +msgid "" +"*X is an example of y. W needs to be initialised using z. This option " +"does that.*" +msgstr "" + +#: ../../reference.rst:91 e781917a9f3f48afa91aebd18cd40bec +msgid "State facts about the machinery and its behaviour." +msgstr "" + +#: ../../reference.rst:92 d1f1a93b4fb9497e88af5fd1a72c1d53 +msgid "*Sub-commands are: a, b, c, d, e, f.*" +msgstr "" + +#: ../../reference.rst:93 a23db9d4aa6341468c61112a782a10f3 +msgid "" +"List commands, options, operations, features, flags, limitations, error " +"messages, etc." +msgstr "" + +#: ../../reference.rst:95 53897478d2db45bd9929c36a35f5e736 +msgid "*You must use a. You must not apply b unless c. Never d.*" +msgstr "" + +#: ../../reference.rst:95 2bf39ccc8d38478b9ec162f2ebc8a267 +msgid "Provide warnings where appropriate." +msgstr "" + +#: ../../reference.rst:100 9630c0b5bfc74b56b89d6f898098ffe7 +msgid "Example from Divio's documentation" +msgstr "" + +#: ../../reference.rst:102 55510f5a91984482add4c52727eafd0b +msgid "" +"Have a look at `an example from our technical reference section " +"`_." +msgstr "" + +#: ../../reference.rst:109 2b1db542e5b54d0f9ddb1ff132df3f87 +msgid "This is a typical reference guide (in this case, for our Divio CLI)." +msgstr "" + +#: ../../reference.rst:111 bcb2793d0ad54ab9bc163ed16597def7 +msgid "" +"Description is all this article does, setting out in a complete and " +"accurate form the functions, commands and options of the tool." +msgstr "" + +#: ../../reference.rst:114 831936de240a4666802123e4da25620f +msgid "" +"It's hardly a friendly or engaging read, but its purpose is to make " +"looking up information about functionality as swift and distraction-free " +"as possible." +msgstr "" + diff --git a/locales/pt_BR/LC_MESSAGES/structure.mo b/locales/pt_BR/LC_MESSAGES/structure.mo new file mode 100644 index 0000000..ca332d3 Binary files /dev/null and b/locales/pt_BR/LC_MESSAGES/structure.mo differ diff --git a/locales/pt_BR/LC_MESSAGES/structure.po b/locales/pt_BR/LC_MESSAGES/structure.po new file mode 100644 index 0000000..eca8a3a --- /dev/null +++ b/locales/pt_BR/LC_MESSAGES/structure.po @@ -0,0 +1,166 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2017-2021, Daniele Procida +# This file is distributed under the same license as the Diátaxis package. +# FIRST AUTHOR , 2021. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Diátaxis \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2021-04-18 20:02-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.9.0\n" + +#: ../../structure.rst:10 395cb4389a0d4544b0be530e0aceb08a +msgid "The structure" +msgstr "" + +#: ../../structure.rst:13 6082091546e4413cae12e94274e4aab7 +msgid "Why isn't this obvious?" +msgstr "" + +#: ../../structure.rst:15 78708428a75548a59f3cdcb34cafb949 +msgid "" +"This structure is clear, and it works, but there is a reason why it's not" +" so obvious, and that is the way the characteristics of each quadrant of " +"the documentation overlap with those of its neighbours in the scheme." +msgstr "" + +#: ../../structure.rst:20 3188c09a459c4ee5a31bab40a457f0cc +msgid "Each of the quadrants is similar to its two neighbours:" +msgstr "" + +#: ../../structure.rst:22 035b4d2280ea444299087f7f25c4054e +msgid "" +"*tutorials and how-to guides* are both concerned with **describing " +"practical steps**" +msgstr "" + +#: ../../structure.rst:23 1f395f68a63645ea81bd90cdb60da6cd +msgid "" +"*how-to guides and technical reference* are both **what we need when we " +"are at work, coding**" +msgstr "" + +#: ../../structure.rst:24 15e9dab97c8b4673b353e4060fb42a1e +msgid "" +"*reference guides and explanation* are both concerned with **theoretical " +"knowledge**" +msgstr "" + +#: ../../structure.rst:25 c77fa646b6c54476b80f8b4e3867f61c +msgid "" +"*tutorials and explanation* are both **most useful when we are " +"studying**, rather than actually working" +msgstr "" + +#: ../../structure.rst:29 802dccf770e741c7a5e6935fecc40827 +msgid "The tendency to collapse" +msgstr "" + +#: ../../structure.rst:31 f222481161fd48c29fbd61ead6cb8e1d +msgid "" +"Given these overlaps, it's not surprising that the different kinds of " +"documentation become confused and mixed in with each other. In fact, " +"there is a natural gravitational pull of these distinct types of " +"documentation to each other, and it is hard to resist. Its effect is to " +"collapse the structure, and that is why so much documentation looks like " +"this:" +msgstr "" + +#: ../../structure.rst:39 4b443f5ee4324e20bf60751fe1c5b198 +msgid "Adoption of the system" +msgstr "" + +#: ../../structure.rst:41 bf5e8522efc94f4f988c2906edee6b7a +msgid "Good examples of the scheme in substantial projects include:" +msgstr "" + +#: ../../structure.rst:43 688809644ea24a96aaee70a985ebe442 +msgid "the `Divio Developer Handbook `_" +msgstr "" + +#: ../../structure.rst:44 ba65eb23fa78426fa2cad0ee3df2fe44 +msgid "" +"`Django's documentation `_" +msgstr "" + +#: ../../structure.rst:45 4b646b4b366742519805c85765e90a13 +msgid "`django CMS's documentation `_" +msgstr "" + +#: ../../structure.rst:47 889c8cc43a734b2aab5a902218633b7c +msgid "" +"It's possible to use the system even in very minimal documentation, for " +"example `CoReport (an open-source COVID-19 reporting project) " +"`_. Here, applying the system creates a " +"framework for future documentation, helping ensure that new material will" +" conform." +msgstr "" + +#: ../../structure.rst:51 6348fc7e79de4011bba00b660f97334e +msgid "" +"Sometimes the documentation is so minimal that not all quadrants are " +"ready to be represented, as in the case of `Getting started with Java and" +" Spring-boot `_, which includes only a tutorial, how-to and" +" reference material." +msgstr "" + +#: ../../structure.rst:55 544c3282cb3d4306bc358b1c4b495194 +msgid "" +"`But I never wanted to do DevOps! `_ is the written material " +"that accompanies a popular workshop. The documentation strictly separate " +"the `tutorial `_, the steps learners are to follow, from the " +"*explanation* (`Further reading `_). Both belong to the " +"*most useful when we are studying* side of the system, so it's natural to" +" include them in a workshop." +msgstr "" + +#: ../../structure.rst:61 7725eae5c4e94c8b96555b69739eeb6b +msgid "" +"In each case though, however minimal or even incomplete, the system is " +"respected and the clear distinction between sections and their purposes " +"will benefit the author and user right away, and help guide the expansion" +" of the material as it develops in the future." +msgstr "" + +#: ../../structure.rst:69 ae0d2a7b864b42408f17de5fd65f1c5f +msgid "About the analysis and its application" +msgstr "" + +#: ../../structure.rst:71 a275a51a3e2d468fa314f79e5bbd78be +msgid "" +"The analysis of documentation in this article is based on several years " +"of experience writing and maintaining documentation, and much time spent " +"considering how to improve it." +msgstr "" + +#: ../../structure.rst:73 bb98112d883348dfa7ecd21bd67af111 +msgid "" +"It’s also based on sound principles that come from a variety of " +"disciplines. For example, its conception of tutorials has a pedagogical " +"basis; it posits a tutor and a learner, and considers using software to " +"be a craft in which abstract understanding of general principles follows " +"from concrete steps that deal with particulars." +msgstr "" + +#: ../../structure.rst:75 3c248c7496964b6f87c78a57738c103e +msgid "" +"The system is presented regularly at talks and interactive workshops. The" +" analysis has been applied to numerous projects, including large internal" +" documentation sets, and has repeatedly procured benefits of usability " +"and maintainability, across a very wide range of technical subject " +"matter." +msgstr "" + diff --git a/locales/pt_BR/LC_MESSAGES/tutorials.mo b/locales/pt_BR/LC_MESSAGES/tutorials.mo new file mode 100644 index 0000000..b63d414 Binary files /dev/null and b/locales/pt_BR/LC_MESSAGES/tutorials.mo differ diff --git a/locales/pt_BR/LC_MESSAGES/tutorials.po b/locales/pt_BR/LC_MESSAGES/tutorials.po new file mode 100644 index 0000000..40febf3 --- /dev/null +++ b/locales/pt_BR/LC_MESSAGES/tutorials.po @@ -0,0 +1,491 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2017-2021, Daniele Procida +# This file is distributed under the same license as the Diátaxis package. +# FIRST AUTHOR , 2021. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Diátaxis \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2021-04-18 20:02-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.9.0\n" + +#: ../../tutorials.rst:4 e7be82d6a64b47d2a80b983978c4a8e0 +msgid "About tutorials" +msgstr "Sobre tutoriais" + +#: ../../tutorials.rst:7 5d8d9659d63c40539bd2a70ea6ff85cf +msgid "" +"Tutorials are **lessons** that take the reader by the hand through a " +"series of steps to complete a project of some kind. Tutorials are " +"**learning-oriented**." +msgstr "" +"Tutoriais são **lições** que pegam o leitor pela mão através de uma " +"série de passos para completar algum tipo de projeto. Tutorias são " +"**orientados-ao-aprendizado**." + +#: ../../tutorials.rst:10 684d53b5c6084af7b1d0ffc54ab1ccae +msgid "" +"Tutorials are what your project needs in order to show a beginner that " +"they can achieve something with it." +msgstr "" +"Tutorial é o que o seu projeto precisa para mostrar a um iniciante o que " +"ele consegue fazer." + +#: ../../tutorials.rst:12 8d4be2ee2a874febaab1bdbd3d966711 +msgid "" +"They are wholly learning-oriented, and specifically, they are oriented " +"towards *learning how* rather than *learning that*." +msgstr "" +"São totalmente orientados para a aprendizagem e, especificamente, são orientados " +"para *aprender como*, em vez de *aprender algo*." + +#: ../../tutorials.rst:19 a66434d452be4bbf9c26ffd52611207e +msgid "" +"**You are the teacher**, and you are **responsible** for what the student" +" will do. Under **your** instruction, the student will execute a series " +"of actions to achieve some **end**." +msgstr "" +"**Você é o professor** e é o **responsável** pelo o quê o aluno fará. " +"Sob **sua** instrução, o aluno executará uma série de ações para atingir algum **objetivo**." + +#: ../../tutorials.rst:21 275ab6b6b6ac46c491c76ed7456eaaf7 +msgid "" +"The end and the actions are up to you, but deciding what they should be " +"can be hard work. The end has to be *meaningful*, but also *achievable* " +"for a complete beginner." +msgstr "" +"Quem define o fim e as ações é você, mas decidir de que jeito elas devem ser " +"pode ser um trabalho árduo. O final deve ser *significativo*, mas também *alcançável* " +"para um completo iniciante." + +#: ../../tutorials.rst:23 18652a5e435149b4b0cffe762886fc5b +msgid "" +"The important thing is that having done the tutorial, the learner is in a" +" position to make sense of the rest of the documentation, and the " +"software itself." +msgstr "" +"O mais importante é que, após ter feito o tutorial, o aluno deve estar " +"em uma posição de entender o resto da documentação e o software por si próprio." + +#: ../../tutorials.rst:25 0c7597277c3e4738954bbfee6ba7d770 +msgid "" +"Most software projects have really bad - or non-existent - tutorials. " +"Tutorials are what will turn your learners into users. **A bad or missing" +" tutorial will prevent your project from acquiring new users.**" +msgstr "" +"A maioria dos projetos de software tem tutoriais que são ruins - ou inexistentes. " +"Os tutoriais são o que vão transformar seus alunos em usuários. **Um tutorial ruim ou ausente " +"impedirá que seu projeto adquira novos usuários**." + +#: ../../tutorials.rst:27 5898c3f046fc4a5c863d61a92c76c22c +msgid "" +"Of the sections describing the four kinds of documentation, this is by " +"far the longest - that's because tutorials are the most misunderstood and" +" most difficult to do well. The best way of teaching is to have a teacher" +" present, interacting with the student. That's rarely possible, and our " +"written tutorials will be at best a far-from-perfect substitute. That's " +"all the more reason to pay special attention to them." +msgstr "" +"Das seções que descrevem os quatro tipos de documentação, esta é de longe a " +"mais longa - isso porque os tutoriais são os mais mal compreendidos e os " +"mais difíceis de fazer bem. A melhor forma de ensinar é tendo um professor " +"presente, interagindo com o aluno. Mas como isso raramente é possível, os nossos " +"tutoriais escritos serão, na melhor das hipóteses, um substituto que está longe de ser perfeito. " +"Esse é mais um motivo para prestar atenção especial a eles." + +#: ../../tutorials.rst:32 68d9bfa1d84c435cbe6ac5b5673b18a2 +msgid "" +"Tutorials need to be useful for the beginner, easy to follow, meaningful " +"and extremely robust, and kept up-to-date. You might well find that " +"writing and maintaining your tutorials can occupy as much time and energy" +" as the the other three parts put together." +msgstr "" +"Os tutoriais precisam ser úteis para o iniciante, fáceis de seguir, significativos, " +"extremamente robustos e mantidos atualizados. Você pode muito bem descobrir que " +"escrever e manter seus tutoriais pode ocupar tanto tempo e energia " +"quanto as outras três partes juntas." + +#: ../../tutorials.rst:39 b9068444cc5b469e8f13f1a93b396137 +msgid "Analogy from cooking" +msgstr "Analogia de cozinhar" + +#: ../../tutorials.rst:46 afb2aa2e2a914bdb9d0eafcc3922a925 +msgid "Consider an analogy of teaching a child to cook." +msgstr "Considere uma analogia de ensinar uma criança a cozinhar." + +#: ../../tutorials.rst:48 5a7d4242bb954912977230fc5c82fe4b +msgid "" +"*What* you teach the child to cook isn’t really important. What’s " +"important is that the child finds it enjoyable, and gains confidence, and" +" wants to do it again." +msgstr "" +"*O que* você ensina a criança a cozinhar não é muito importante. O " +"importante é que ela goste, ganhe confiança e " +"queira fazer de novo." + +#: ../../tutorials.rst:50 cd8a1cd85e03436fb97082e423f86531 +msgid "" +"*Through* the things the child does, it will learn important things about" +" cooking. It will learn what it is like to be in the kitchen, to use the " +"utensils, to handle the food." +msgstr "" +"*Por meio* das coisas que a criança faz, ela aprenderá importantes coisas sobre " +"culinária. Vai aprender como é estar na cozinha, a usar os " +"utensílios, a como manusear a comida." + +#: ../../tutorials.rst:53 dc23d766d7a04da38ba2544cd5c14b3f +msgid "" +"This is because using **software, like cooking, is a matter of craft**. " +"It’s knowledge - but it is *practical* knowledge, not *theoretical* " +"knowledge." +msgstr "" +"Isso ocorre porque **assim como cozinhar, usar software é uma questão de artesanato.** " +"É conhecimento - mas é um conhecimento prático e não teórico." + +#: ../../tutorials.rst:55 9bf83a2b618840dd85687ea31d61f506 +msgid "When we learn a new craft or skill, we always begin learning it by doing." +msgstr "Quando aprendemos um novo ofício ou habilidade, sempre começamos a aprender fazendo." + +#: ../../tutorials.rst:60 e6924eb6e21044e9a7dc6983a3b125f5 +msgid "How to write good tutorials" +msgstr "Como escrever bons tutoriais" + +#: ../../tutorials.rst:64 602ba6d07b4a4830bbf106dc77e08d76 +msgid "abstraction, generalisation" +msgstr "abstração, generalismo" + +#: ../../tutorials.rst:65 c27bfcc66e5045729a8f2ed8222acd20 +msgid "explanation" +msgstr "explicação" + +#: ../../tutorials.rst:66 11373ce921744918b5b3a36a706f48ab +msgid "choices" +msgstr "escolhas" + +#: ../../tutorials.rst:67 f5bfcab6da8e41b89b9ccc82d3300df2 +msgid "information" +msgstr "informação" + +#: ../../tutorials.rst:71 9ac1d28a3b894ad5bedc023d85b47a1f +msgid "Allow the user to learn by doing" +msgstr "Permita que usuário aprenda fazendo" + +#: ../../tutorials.rst:73 fbd07a2f063d4d4ab476daab8e136418 +msgid "" +"**In the beginning, we only learn anything by doing** - it’s how we learn" +" to talk, or walk." +msgstr "**No começo, todos nós só aprendemos fazendo** - e é assim que aprendemos " +"a falar, ou andar." + +#: ../../tutorials.rst:75 de19e6ea600442c38a7599cefb0a81c8 +msgid "" +"In your software tutorial, your learner needs to *do* things. The " +"different things that they do while following your tutorial need to cover" +" a wide range of tools and operations, building up from the simplest ones" +" at the start to more complex ones." +msgstr "" +"No seu tutorial de software, o aluno precisa *fazer* coisas. As " +"diferentes coisas que eles fazem enquanto seguem seu tutorial precisam cobrir " +"uma ampla gama de ferramentas e operações, desde as mais simples " +"no início até as mais complexas." + +#: ../../tutorials.rst:79 3e388ed9bc6a40fe99ee68a37d5e5afb +msgid "Get the user started" +msgstr "Primeiros passos com o usuário" + +#: ../../tutorials.rst:81 9dc19abd6b99487eae0ea53f71fafc22 +msgid "" +"It’s perfectly acceptable if your beginner’s first steps are hand-held " +"baby steps. It’s also perfectly acceptable if what you get the beginner " +"to do is not the way an experienced person would, or even if it’s not the" +" ‘correct’ way - a tutorial for beginners is not the same thing as a " +"manual for best practice." +msgstr "" +"É perfeitamente aceitável se os primeiros passos do iniciante forem passos de bebê. " +"Também é perfeitamente aceitável se o que você faz com que o iniciante " +"não seja da mesma maneira que uma pessoa experiente faria, ou que até mesmo não seja " +"da forma 'mais correta possível' - um tutorial para iniciantes não é a mesma coisa " +"que um manual das melhores práticas." + +#: ../../tutorials.rst:83 9fae19d3254a4da195d6575d8af29706 +msgid "" +"The point of a tutorial is to get your learner **started on their " +"journey**, not to get them to a final destination." +msgstr "" +"O objetivo de um tutorial é fazer com que o aluno **inicie a jornada**, " +"não levá-lo a um destino final." + +#: ../../tutorials.rst:87 054a074bc8474c76b57dc5748bb148a6 +msgid "Make sure that your tutorial works" +msgstr "Certifique-se que o tutorial funciona" + +#: ../../tutorials.rst:89 d297327539ab4871bcb37cf3cae1f2a1 +msgid "" +"One of your jobs as a tutor is to inspire the beginner’s confidence: in " +"the software, in the tutorial, in the tutor and, of course, in their own " +"ability to achieve what’s being asked of them." +msgstr "" +"Um de seus trabalhos como tutor é inspirar a confiança do iniciante: no " +"software, no tutorial, no tutor, e claro, em sua própria capacidade " +"de realizar o que está sendo pedido deles." + +#: ../../tutorials.rst:91 ad488fbe7dd94c27af686809c30ab17d +msgid "" +"There are many things that contribute to this. A friendly tone helps, as " +"does consistent use of language, and a logical progression through the " +"material. But the single most important thing is that **what you ask the " +"beginner to do must work**. The learner needs to see that the actions you" +" ask them to take have the effect you say they will have." +msgstr "" +"Existem muitas coisas que contribuem para isso. Um tom amigável ajuda, " +"assim como o uso consistente da linguagem e uma progressão lógica através do " +"material. Mas o mais importante é que **o que você pede ao para o " +"iniciante fazer deve funcionar**. O aluno precisa ver que as ações que você " +"pede cumpre o resultado que você diz que terão." + +#: ../../tutorials.rst:93 b547fb9ab10a428bbf99b8d072307374 +msgid "" +"If the learner's actions produce an error or unexpected results, your " +"tutorial has failed - even if it’s not your fault. When your students are" +" there with you, you can rescue them; if they’re reading your " +"documentation on their own you can’t - so you have to prevent that from " +"happening in advance. This is without doubt easier said than done." +msgstr "" +"Se as ações do aluno produzirem um erro ou resultados inesperados, seu " +"tutorial falhou - mesmo que a culpa não seja sua. Quando seus alunos estão " +"pessoalmente com você, você consegue ajuda-los; mas se eles estão lendo " +"sua documentação por conta própria, não - então você precisa evitar " +"que isso aconteça com antecedência. Sem dúvida, é mais fácil falar isso do que fazer." + +#: ../../tutorials.rst:97 3b2106b48b8647719e7ccbecc28e4a80 +msgid "Ensure the user sees results immediately" +msgstr "Certifique-se que o usuário vê resultados imediatos" + +#: ../../tutorials.rst:99 9886ec52423b464fa40abb18ebbc1e37 +msgid "" +"**Everything the learner does should accomplish something comprehensible," +" however small.** If your student has to do strange and incomprehensible " +"things for two pages before they even see a result, that’s much too long." +" The effect of every action should be visible and evident as soon as " +"possible, and the connection to the action should be clear." +msgstr "" +"**Tudo o que o aluno faz deve ser fácil de entender, " +"por menor que seja.** Se o seu aluno tem que fazer coisas estranhas e incompreensíveis " +"por duas páginas antes mesmo de ver o resultado, isso é longo demais. " +"O efeito de cada ação deve ser visível e evidente o mais rápido possível, " +"e a conexão com a ação deve ser clara." + +#: ../../tutorials.rst:101 cafdf735b50e49ec85cebeda5cf6d708 +msgid "" +"The conclusion of each section of a tutorial, or the tutorial as a whole," +" must be a meaningful accomplishment." +msgstr "" +"A conclusão de uma seção ou de um tutorial inteiro " +"deve ser uma realização significativa." + +#: ../../tutorials.rst:105 03c1c791dd444ea5b69719ce3734a8fd +msgid "Make your tutorial repeatable" +msgstr "Seu tutorial deve ser reprozível" + +#: ../../tutorials.rst:107 eb65a3ed3e2a43188ab2172ee8b83e1a +msgid "" +"**Your tutorial must be reliably repeatable.** This not easy to achieve: " +"people will be coming to it with different operating systems, levels of " +"experience and tools. What’s more, any software or resources they use are" +" quite likely themselves to change in the meantime." +msgstr "" +"**Seu tutorial deve ser reproduzível de forma confiável**. Isso não é fácil de conseguir: " +"chegarão pessoas com diferentes sistemas operacionais, níveis de experiência " +"e ferramentas ao seu tutorial. Além disso, qualquer software ou recurso que eles " +"usem provavelmente sofrerão alterações nesse meio tempo." + +#: ../../tutorials.rst:109 252eb30c86b3423e859f6a43a5a6f234 +msgid "The tutorial has to work for all of them, every time." +msgstr "O tutorial deve funcionar para todos que tentem usar, toda vez." + +#: ../../tutorials.rst:111 4b7a28606d4542569801f6c3232ad111 +msgid "" +"Tutorials unfortunately need regular and detailed testing to make sure " +"that they still work." +msgstr "" +"Infelizmente os tutoriais precisam de um teste regular e detalhado para se certificar " +"que as coisas funcionam." + +#: ../../tutorials.rst:115 c37595f98b154502b46a3bc857e4dd9d +msgid "Focus on concrete steps, not abstract concepts" +msgstr "Foque em passos concretos, não em conceitos abstratos" + +#: ../../tutorials.rst:117 b932fdbd945e4fb9a5ea24a0b24fe5c3 +msgid "" +"**Tutorials need to be concrete**, built around specific, particular " +"actions and outcomes." +msgstr "" +"**Tutoriais precisam ser concretos**, construidos em torno de resultados " +"específicos e particulares." + +#: ../../tutorials.rst:119 b1bd3069fd3e47c78927731596bfe5b9 +msgid "" +"The temptation to introduce abstraction is huge; it is after all how most" +" computing derives its power. But all learning proceeds from the " +"particular and concrete to the general and abstract, and asking the " +"learner to appreciate levels of abstraction before they have even had a " +"chance to grasp the concrete is poor teaching." +msgstr "" +"A tentação de introduzir uma abstração é enorme; afinal, é como a maior " +"parte da computação fuciona. Mas toda aprendizagem parte do específico e concreto " +"para o geral e abstrato, e pedir ao aluno que aprecie níveis de " +"abstração antes mesmo de ter a chance de compreender o concreto é um ensino pobre." + +#: ../../tutorials.rst:123 af4e3d587c9a4e36bb3c64860df84809 +msgid "Provide the minimum necessary explanation" +msgstr "Forneça o mínimo necessário de explicação" + +#: ../../tutorials.rst:125 6b8da4add8c94cb2aa4b5cbdb6c6f53d +msgid "" +"**Don’t explain anything the learner doesn’t need to know in order to " +"complete the tutorial.** Extended discussion is important - just not in a" +" tutorial. In a tutorial, it is an obstruction and a distraction. Only " +"the bare minimum is appropriate. Instead, link to explanations elsewhere " +"in the documentation." +msgstr "" +"**Não explique nada além do que o aluno precisa saber para concluir o tutorial.** " +"Uma discussão extensa é importante - mas não em um tutorial. No tutorial, " +"é uma obstrução e uma distração. Apenas o mínimo é apropriado. Em vez disso, " +"faça referências a explicações em outras partes da documentação." + +#: ../../tutorials.rst:129 dfb29a12bdbb49f7b9db877412849371 +msgid "Focus only on the steps the user needs to take" +msgstr "Foque apenas nos passos que o usuário precisa dar" + +#: ../../tutorials.rst:131 ec46060574464f439b6fdadde022f75c +msgid "" +"**Your tutorial needs to be focused on the task in hand.** Maybe the " +"command you’re introducing has many other options, or maybe there are " +"different ways to access a certain API. It doesn’t matter: right now, " +"your learner does not need to know about those in order to make progress." +msgstr "" +"**Seu tutorial precisa ser focado na tarefa em questão**. Talvez o " +"caminho que você está introduzindo tenha muitas outras opções ou talvez " +"existam diferentes maneiras de acessar uma determinada API. Não importa: " +"por enquanto, seu aluno não precisa saber sobre eles para fazer progresso." + +#: ../../tutorials.rst:136 2496f25046144ebd8b59724b4af56c59 +msgid "The language of tutorials" +msgstr "A linguagem dos tutoriais" + +#: ../../tutorials.rst:138 e61690dfa958453fa04c6f02c2f5c1c6 +msgid "*In this tutorial, you will...*" +msgstr "*Neste tutorial, você vai...*" + +#: ../../tutorials.rst:139 aada4314f66d42e5a25d0050193f6e78 +msgid "" +"Describe what the learner will accomplish (note - not: \"you will " +"learn...\")." +msgstr "" +"Explique o que o aluno irá realizar (note - não diga: \"você vai " +"aprender...\")." + +#: ../../tutorials.rst:140 b4c6a1ef5c6b4d24807aa9f0979e3f76 +msgid "*First, do x. Now, do y. Now that you have done y, do z.*" +msgstr "*Primeiro, faça x. Agora, faça y. E depois que você tiver " +"feito y, faça z.*" + +#: ../../tutorials.rst:141 920e701c5d184b3c82e84abae416e698 +msgid "No room for ambiguity or doubt." +msgstr "Sem espaço para ambiguidade ou dúvidas." + +#: ../../tutorials.rst:142 2d86b65be06540e3a5c17ab8181f13a8 +msgid "" +"*We must always do x before we do y because... (see Explanation for more " +"details).*" +msgstr "" +"*Nós devemos sempre fazer x antes de y porquê... (veja Explanação para mais " +"detalhes).*" + +#: ../../tutorials.rst:143 4f8ee2fdbd2645c9baeee861981bd26d +msgid "" +"Provide minimal explanation of actions in the most basic language " +"possible. Link to more detailed explanation." +msgstr "" +"Forneça o mínimo de explicação das etapas na forma mais simples " +"possível. Aponte um link para uma explicação mais detalhada." + +#: ../../tutorials.rst:144 15a6336c3b144f94b761e881944e9fd3 +msgid "*The output should look something like this...*" +msgstr "*O resultado deveria se parecer com algo assim...*" + +#: ../../tutorials.rst:145 4fd7bf941375483d8ac8f8a73d136381 +msgid "Give your learner clear expectations." +msgstr "Dê ao aluno claras expectativas." + +#: ../../tutorials.rst:146 ddd4b6bc124641c29d6c6e768bd21d25 +msgid "*Notice that... Remember that...*" +msgstr "*Note que... Lembre-se que...*" + +#: ../../tutorials.rst:147 ed569e2e30284c4b83a80bce6e363e51 +msgid "" +"Give your learner plenty of clues to help confirm they are on the right " +"track and orient themselves." +msgstr "" +"Dê ao aluno muitas provas que ajude ele a confirmar que está no caminho certo " +"e que ajuda ele a se orientar sozinho." + +#: ../../tutorials.rst:149 3747bee112f346a58bd85bf5b193cefb +msgid "*You have built a secure, three-layer hylomorphic stasis engine...*" +msgstr "*Você tem que construir um motor de tesla seguro de três camadas...*" + +#: ../../tutorials.rst:149 0762a36bc26b49a6adb74652925f7cd9 +msgid "" +"Describe (and admire, in a mild way) what your learner has accomplished " +"(note - not: \"you have learned...\")" +msgstr "" +"Descreva (e admire, de maneira suave) o que o aluno realizou " +"(note - não diga: \"você aprendeu...\")" + +#: ../../tutorials.rst:154 6b99140a43784137b9fb15b98b7e7e0b +msgid "Example from Divio's documentation" +msgstr "Exemplo da documentação Divio" + +#: ../../tutorials.rst:156 a30ad9f2dd7d4b5294c413976e84e865 +msgid "" +"Have a look at `our tutorials " +"`_." +msgstr "" +"Dê uma olhada em `nossos tutoriais " +"`_." + +#: ../../tutorials.rst:163 c3f0167b125340168b79d4fd9ce3c4bb +msgid "" +"In particular, see the tutorial for Django. The promise that the tutorial" +" makes is: if you have the basic knowledge required to follow this " +"tutorial, and you follow its directions, you will end up with with a " +"working Django web application, complete with Postgres database, S3 media" +" storage, and so on. In order to work as a tutorial, it has to fulfil " +"that promise." +msgstr "" +"Em particular, consulte o tutorial do Django. A promessa que o tutorial " +"faz é: se você tiver o conhecimento básico necessário para seguir este " +"tutorial e seguir suas instruções, terá um aplicativo da Web Django " +"funcional, completo com banco de dados Postgres, armazenamento de mídia S3 " +"e assim por diante. Para funcionar como um tutorial, ele precisa cumprir " +"uma promessa." + +#: ../../tutorials.rst:168 bae53eb5313446e7b886685dac7039a5 +msgid "" +"Note that it doesn’t tell you what you will *learn*, just what you will " +"*do*. The learning comes out of that doing. The tutorial takes full " +"responsibility for what you will do and the order in which you will do " +"it." +msgstr "" +"Observe que ele não diz o que você aprenderá, apenas o que você fará. " +"O aprendizado vem desse fazer. O tutorial assume total responsabilidade" +"pelo que você fará e pela ordem em que o fará." + diff --git a/requirements.txt b/requirements.txt index 9f1aeee..b4277eb 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,6 +3,7 @@ Babel==2.9.0 beautifulsoup4==4.9.3 certifi==2020.12.5 chardet==4.0.0 +click==7.1.2 colorama==0.4.4 docutils==0.16 furo==2021.4.11b34 @@ -22,6 +23,7 @@ snowballstemmer==2.1.0 soupsieve==2.2.1 Sphinx==3.5.4 sphinx-autobuild==2021.3.14 +sphinx-intl==2.0.1 sphinx-rtd-theme==0.5.2 sphinxcontrib-applehelp==1.0.2 sphinxcontrib-devhelp==1.0.2