From a2f7f90ed4a5d402eb0a9684cf4c20cb2cede546 Mon Sep 17 00:00:00 2001 From: Florian Stolzenhain Date: Fri, 18 Nov 2022 16:41:29 +0100 Subject: [PATCH 1/5] Content: i18n: Draft: make up new folder structure for now, we clone the English original --- docs/_i18n/de/guide/docs-as-code.rst | 105 +++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 docs/_i18n/de/guide/docs-as-code.rst diff --git a/docs/_i18n/de/guide/docs-as-code.rst b/docs/_i18n/de/guide/docs-as-code.rst new file mode 100644 index 0000000000..5fc9cc0b04 --- /dev/null +++ b/docs/_i18n/de/guide/docs-as-code.rst @@ -0,0 +1,105 @@ +Docs as Code +============ + +:author: `Eric Holscher `_ & the Write the Docs community + +Documentation as Code (*Docs as Code*) refers to a philosophy that you should be writing documentation with the same tools as code: + +* Issue Trackers +* Version Control (Git) +* Plain Text Markup (Markdown, reStructuredText, Asciidoc) +* Code Reviews +* Automated Tests + +This means following the same workflows as development teams, +and being integrated in the product team. +It enables a culture where writers and developers both feel ownership of documentation, +and work together to make it as good as possible. + +Generally a *Docs as Code* approach gives you the following benefits: + +* Writers integrate better with development teams +* Developers will often write a first draft of documentation +* You can block merging of new features if they don't include documentation, which incentivizes developers to write about features while they are fresh + +There is a lot more to building a proper *Docs as Code* workflow. +There are a couple books we recommend that you check out: + +* `Docs Like Code `_ - Anne Gentle +* `Modern Technical Writing `_ - Andrew Etter + +In addition, there is an open source tool-chain which shows how the docs-as-code approach can be implemented + +* `docToolchain `_ + +*Docs as Code* at Write the Docs +---------------------------------- + +Write the Docs has had a number of talks that touch on this topic over the years. + +**2015 North America** + +* `Riona MacNamara`_ talked about how adopting *Docs as Code* has completely transformed how Google does documentation. + +**2016 North America** + +* We had a `panel`_ with folks from Rackspace, Microsoft, Balsamiq, and Twitter, all talking about how they are adopting these practices. + +**2016 Europe** + +* `Margaret Eker and Jennifer Roundeau`_ from Rackspace & Capital One, it was a great overview of *Docs as Code*. +* `Rachel Whitten`_ from Pantheon give a talk on their implementation of these approaches. + +**2017 North America** + +* `Jodie Putrino`_ from F5 gave a practical account of her experience developing docs like code. + +**2018 Europe** + +* `Predrag Mandic`_ talked about how the "documentation is code" principle saves money and time, empowers documentarians, simplifies processes around testing documentation and brings happiness to a diverse customer base. + +**2019 Europe** + +* `Jen Lambourne`_ shared the UK Government Digital Service's experience adopting a docs as code approach. + +**2020 Europe** + +* `Diana Lakatos`_ showed various fully remote processes platformOS developed to help community members contribute content and code to their developer portal, including why they follow the docs as code approach, how they developed an editorial workflow that can work for all contributors, and how they implemented it through GitHub. + +**2021 North America** + +* `Swapnil Ogale`_ provided his take on transitioning from traditional tech writing tools to a docs as code approach. + +**2022 North America** + +* `Marcia Riefer Johnston and Dave May`_ from Amazon Web Services (AWS) told the story of their team's move to docs as code: what worked, what didn't, what's next. + +The *Docs as Code* concepts are widely practiced in the software industry, +and are gaining adoption in the writing community. + +.. _Riona MacNamara: https://www.youtube.com/watch?v=EnB8GtPuauw +.. _panel: https://www.youtube.com/watch?v=Y2TGwUPb8R4 +.. _Margaret Eker and Jennifer Roundeau: https://www.youtube.com/watch?v=JvRd7MmAxPw +.. _Rachel Whitten: https://www.youtube.com/watch?v=dHdBsNxtKeI +.. _Jodie Putrino: https://www.youtube.com/watch?v=Mzu-c-FoOdw +.. _Predrag Mandic: https://www.youtube.com/watch?v=oW7rWJ2xNZU +.. _Jen Lambourne: https://www.youtube.com/watch?v=Ql9Il7tssik +.. _Diana Lakatos: https://www.youtube.com/watch?v=zm5Iw7jsyC4 +.. _Swapnil Ogale: https://www.youtube.com/watch?v=FQ7DkPOw3Cc +.. _Marcia Riefer Johnston and Dave May: https://www.youtube.com/watch?v=Cxuo3udElcE + +*Docs as Code* at other Conferences, Video Casts and Articles +------------------------------------------------------------- + +The approach has been presented at several other conferences or just video casts by different speakers. + +**2017** + +* Software Architecture Summit 2017, Berlin, Germany: Gernot Starke, Ralf D. Müller: `Hitchhiker’s Guide to Architecture Documentation `_. (Half-Day-Workshop) + +**2018** + +* I'd rather be writing: Tom Johnson: `Docs as code tools and workflows presentation `_ +* Greach, Madrid, Spain: Ralf D. Müller: `Docs as code: arc42, AsciiDoc, Gradle & Co combined `_ +* JavaMagazin: Gernot Starke, Ralf D. Müller: `Hitchhiker’s Guide to Docs as Code `_ (German) +* FrOSCon, Sankt Augustin, Germany: Christoph Stoettner: `Documentation with any Editor `_ From 10ad3c40ccee3bb41f9526219d2643a26f91bb3b Mon Sep 17 00:00:00 2001 From: Florian Stolzenhain Date: Fri, 18 Nov 2022 16:41:47 +0100 Subject: [PATCH 2/5] Content: i18n: Draft: PM --- docs/_i18n/de/guide/docs-as-code.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/_i18n/de/guide/docs-as-code.rst b/docs/_i18n/de/guide/docs-as-code.rst index 5fc9cc0b04..b95e85ddb7 100644 --- a/docs/_i18n/de/guide/docs-as-code.rst +++ b/docs/_i18n/de/guide/docs-as-code.rst @@ -1,3 +1,5 @@ +.. TODO: DE + Docs as Code ============ From 44f0b2dcff8152069a3aa7ede453106ebb57e11d Mon Sep 17 00:00:00 2001 From: Florian Stolzenhain Date: Fri, 18 Nov 2022 15:42:12 +0000 Subject: [PATCH 3/5] Content: i18n: translate 1st blob --- docs/_i18n/de/guide/docs-as-code.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/_i18n/de/guide/docs-as-code.rst b/docs/_i18n/de/guide/docs-as-code.rst index b95e85ddb7..4b2ef0432f 100644 --- a/docs/_i18n/de/guide/docs-as-code.rst +++ b/docs/_i18n/de/guide/docs-as-code.rst @@ -7,18 +7,22 @@ Docs as Code Documentation as Code (*Docs as Code*) refers to a philosophy that you should be writing documentation with the same tools as code: -* Issue Trackers -* Version Control (Git) -* Plain Text Markup (Markdown, reStructuredText, Asciidoc) +.. TODO: Proofread + +* Ticketsysteme +* Versionskontrolle (Git) +* Klartext-Syntax (Markdown, reStructuredText, Asciidoc) * Code Reviews -* Automated Tests +* Automatisierte Tests + +Es bedeutet, demselben Workflow wie Entwicklungs-Teams zu folgen +und ins Produkt-Team eingebunden zu sein. +Das ermöglicht ein Umfeld, in dem Texter und Entwickler gleichermaßen die Verantwortung für Dokumentation haben +und zusammenarbeiten, um sie so gut wie möglich zu gestalten. -This means following the same workflows as development teams, -and being integrated in the product team. -It enables a culture where writers and developers both feel ownership of documentation, -and work together to make it as good as possible. +Grundsätzlich bietet ein „Docs-as-Code“-Ansatz folgende Vorteile: -Generally a *Docs as Code* approach gives you the following benefits: +.. TODO: DE * Writers integrate better with development teams * Developers will often write a first draft of documentation From 76d130a88d09b5de93627ebf125cedec01a6411a Mon Sep 17 00:00:00 2001 From: Florian Stolzenhain Date: Fri, 18 Nov 2022 17:44:16 +0100 Subject: [PATCH 4/5] Content: i18n: translate 2nd blob --- docs/_i18n/de/guide/docs-as-code.rst | 32 ++++++++++++---------------- 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/docs/_i18n/de/guide/docs-as-code.rst b/docs/_i18n/de/guide/docs-as-code.rst index 4b2ef0432f..594fc4a0e4 100644 --- a/docs/_i18n/de/guide/docs-as-code.rst +++ b/docs/_i18n/de/guide/docs-as-code.rst @@ -1,43 +1,39 @@ -.. TODO: DE - Docs as Code ============ -:author: `Eric Holscher `_ & the Write the Docs community +:author: `Eric Holscher `_ & die Write-the-Docs-Community -Documentation as Code (*Docs as Code*) refers to a philosophy that you should be writing documentation with the same tools as code: +Dokumentation als Code (*Docs as Code*) bezeichnet die Auffassung, daß Dokumentation mit denselben Mitteln wie Code geschrieben werden sollte: -.. TODO: Proofread - -* Ticketsysteme +* Ticketsystemen * Versionskontrolle (Git) * Klartext-Syntax (Markdown, reStructuredText, Asciidoc) * Code Reviews -* Automatisierte Tests +* Automatisierten Tests Es bedeutet, demselben Workflow wie Entwicklungs-Teams zu folgen und ins Produkt-Team eingebunden zu sein. -Das ermöglicht ein Umfeld, in dem Texter und Entwickler gleichermaßen die Verantwortung für Dokumentation haben -und zusammenarbeiten, um sie so gut wie möglich zu gestalten. +Das ermöglicht ein Umfeld, in dem technische Redakteure und Entwickler gleichermaßen die Verantwortung für Dokumentation tragen +und darin zusammenarbeiten, sie so nützlich wie möglich zu gestalten. Grundsätzlich bietet ein „Docs-as-Code“-Ansatz folgende Vorteile: -.. TODO: DE +* Redakteure fügen sich besser in Entwicklungs-Teams ein +* Entwickler schreiben häufig einen ersten Dokumentations-Entwurf +* Das Mergen neuer Features kann verhindert werden, wenn keine Dokumentation enthalten ist. Das motiviert Entwickler dazu, über Features zu schreiben, solange sie noch neu sind -* Writers integrate better with development teams -* Developers will often write a first draft of documentation -* You can block merging of new features if they don't include documentation, which incentivizes developers to write about features while they are fresh - -There is a lot more to building a proper *Docs as Code* workflow. -There are a couple books we recommend that you check out: +Es gehört mehr dazu, einen richtigen „_Docs-as-Code_“-Workflow zu aufzubauen. +Wir empfehlen, zum Thema einige Bücher zu konsultieren: * `Docs Like Code `_ - Anne Gentle * `Modern Technical Writing `_ - Andrew Etter -In addition, there is an open source tool-chain which shows how the docs-as-code approach can be implemented +Außerdem existitiert eine Open-Source-Toolchain, die erklärt, wie der „_Docs-as-Code_“-Ansatz umgesetzt werden kann * `docToolchain `_ +.. TODO: DE + *Docs as Code* at Write the Docs ---------------------------------- From 141c164f6066cc0d6273e44b7daf46e3b4d0d0c4 Mon Sep 17 00:00:00 2001 From: Florian Stolzenhain Date: Fri, 18 Nov 2022 17:54:10 +0100 Subject: [PATCH 5/5] i18n: Content: Sphinx: fix formatting --- docs/_i18n/de/guide/docs-as-code.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_i18n/de/guide/docs-as-code.rst b/docs/_i18n/de/guide/docs-as-code.rst index 594fc4a0e4..b40f7a5527 100644 --- a/docs/_i18n/de/guide/docs-as-code.rst +++ b/docs/_i18n/de/guide/docs-as-code.rst @@ -22,13 +22,13 @@ Grundsätzlich bietet ein „Docs-as-Code“-Ansatz folgende Vorteile: * Entwickler schreiben häufig einen ersten Dokumentations-Entwurf * Das Mergen neuer Features kann verhindert werden, wenn keine Dokumentation enthalten ist. Das motiviert Entwickler dazu, über Features zu schreiben, solange sie noch neu sind -Es gehört mehr dazu, einen richtigen „_Docs-as-Code_“-Workflow zu aufzubauen. +Es gehört mehr dazu, einen richtigen „*Docs-as-Code*“-Workflow zu aufzubauen. Wir empfehlen, zum Thema einige Bücher zu konsultieren: * `Docs Like Code `_ - Anne Gentle * `Modern Technical Writing `_ - Andrew Etter -Außerdem existitiert eine Open-Source-Toolchain, die erklärt, wie der „_Docs-as-Code_“-Ansatz umgesetzt werden kann +Außerdem existitiert eine Open-Source-Toolchain, die erklärt, wie der „*Docs-as-Code*“-Ansatz umgesetzt werden kann * `docToolchain `_