diff --git a/README.md b/README.md index b43128d10f..97a01ba7bc 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ WIP (Work In Progress) Docs on how to do this: 2. Make sure the directory `videos//` is included in the Video Archive `toctree` in `docs/videos/index.rst`. -3. In the [virtual environment](#prerequisites-for-generating-the-docs-locally), switch to the `docs` directory and run `BUILD_VIDEOS=True make html`. +3. In the [virtual environment](#prerequisites-for-generating-the-docs-locally), switch to the `docs` directory and run `make html`. 4. Commit the *relevant* changed files: @@ -34,7 +34,7 @@ WIP (Work In Progress) Docs on how to do this: 5. If you want to preview locally: - 1. Run `BUILD_VIDEOS=True make livehtml` and browse the new video pages at `http://127.0.0.1:8888`. + 1. Run `make livehtml` and browse the new video pages at `http://127.0.0.1:8888`. ### Prerequisites for generating the docs locally diff --git a/docs/_data/2015.eu.speakers.yaml b/docs/_data/2015.eu.speakers.yaml index 697bdbd44c..3df7898ee5 100644 --- a/docs/_data/2015.eu.speakers.yaml +++ b/docs/_data/2015.eu.speakers.yaml @@ -12,7 +12,7 @@ \ for software testing\ncan ease the burden of keeping documentation up to date.\ \

\n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/tested-and-correct-how-to-make-sure-your-documentation-keeps-working-adangoor + path: https://www.youtube.com/watch?v=PoVwyPipHzc series: Write the Docs EU series_slug: eu slug: tested-and-correct-how-to-make-sure-your-documentation-keeps-working-adangoor @@ -42,7 +42,7 @@ \ examples. The target audience may have a strong\nbackground in science, computer\ \ science, both or neither.

\n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/the-quest-for-scientific-credit-for-software-documentation-ajaruga + path: https://www.youtube.com/watch?v=Qg7lOWyT2mo series: Write the Docs EU series_slug: eu slug: the-quest-for-scientific-credit-for-software-documentation-ajaruga @@ -63,7 +63,7 @@ \ one)\n\n

... with plenty of real-world examples of doing it right\ \ and wrong.

\n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/before-the-docs-writing-for-user-interfaces-baitman + path: https://www.youtube.com/watch?v=LemM9PHDX6w series: Write the Docs EU series_slug: eu slug: before-the-docs-writing-for-user-interfaces-baitman @@ -86,7 +86,7 @@ \ audience reactions to those\npresentations and how I have iterated my presentations\ \ in sync with changes\nto product and branding.

\n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/documenting-your-story-crafting-a-good-presentation-cward + path: https://www.youtube.com/watch?v=2JacBpYizRw series: Write the Docs EU series_slug: eu slug: documenting-your-story-crafting-a-good-presentation-cward @@ -112,7 +112,7 @@ \ making sure that we, as documentarians, aren't just writing - we're shaping the discussion about\n\ \ when and how docs make our teams, organizations, and communities better.

\n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/all-roads-might-not-lead-to-docs-celmore + path: https://www.youtube.com/watch?v=NKYSdEasJ-8 series: Write the Docs EU series_slug: eu slug: all-roads-might-not-lead-to-docs-celmore @@ -136,7 +136,7 @@ \ be a professional voice actor or videographer to\ncreate a screencast, even\ \ a writer can create something wonderful.

\n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/screencasting-101-dpotter + path: https://www.youtube.com/watch?v=vz5HYGqFIOM series: Write the Docs EU series_slug: eu slug: screencasting-101-dpotter @@ -164,7 +164,7 @@ \ it is not going to diminish\nanytime soon either. This talk attempts to teach\ \ one how to make digital\ncommunication as painless as possible.

\n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/how-to-write-an-email-ecaine + path: https://www.youtube.com/watch?v=Ja-4t8Ufv6Y series: Write the Docs EU series_slug: eu slug: how-to-write-an-email-ecaine @@ -191,7 +191,7 @@ \ terms and expand it into a glossary, a thesaurus, a taxonomy,\nor even a full-fledge\ \ ontology.

\n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/whatchamacallit-controlled-vocabularies-for-technical-writers-eboillat + path: https://www.youtube.com/watch?v=0kg-6YCDg64 series: Write the Docs EU series_slug: eu slug: whatchamacallit-controlled-vocabularies-for-technical-writers-eboillat @@ -212,7 +212,7 @@ \ quality, working with diverse communities,\nfostering innovation, and carnivorous\ \ plants.

\n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/gardening-open-docs-florian-scholz-jean-yves-perrier + path: https://www.youtube.com/watch?v=q9_hG-Uu80I series: Write the Docs EU series_slug: eu slug: gardening-open-docs-florian-scholz-jean-yves-perrier @@ -239,7 +239,7 @@ \ of\nreduced development time, reduced effort, and reduced duplication. We can\n\ all of this by documenting once, and re-using across multiple projects!

\n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/generating-docs-from-apis-jhannaford + path: https://www.youtube.com/watch?v=iCQkhSXGfOU series: Write the Docs EU series_slug: eu slug: generating-docs-from-apis-jhannaford @@ -265,7 +265,7 @@ \ much longer history of teaching engineers to write documentation\n\n
  • Efforts\ \ to make technical writing into an independent profession
    • \n\n\n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/back-to-the-future-what-can-documentarians-learn-from-the-past-jrondeau + path: https://www.youtube.com/watch?v=_SW84nNlgmo series: Write the Docs EU series_slug: eu slug: back-to-the-future-what-can-documentarians-learn-from-the-past-jrondeau @@ -291,7 +291,7 @@ \ own timidity to create room for the\ninspiration and creativity needed to bring\ \ the docs' subject alive.

    \n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/free-your-mind-and-your-docs-will-follow-pkeegan + path: https://www.youtube.com/watch?v=H_kC8_hfpe8 series: Write the Docs EU series_slug: eu slug: free-your-mind-and-your-docs-will-follow-pkeegan @@ -317,7 +317,7 @@ \ writers must also obey them. Or not. And what that means for the\nsuccess of\ \ documentation in a Free Software project.

    \n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/judas-priest-ate-my-scrum-master-padams + path: https://www.youtube.com/watch?v=35AzPlwAhNg series: Write the Docs EU series_slug: eu slug: judas-priest-ate-my-scrum-master-padams @@ -349,7 +349,7 @@ \ to https://twitter.com/thenextmacgyver)\"\

    \n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/macgyvering-your-docs-proeland + path: https://www.youtube.com/watch?v=Y2QxSTJ1jVs series: Write the Docs EU series_slug: eu slug: macgyvering-your-docs-proeland @@ -371,7 +371,7 @@ \ and guidelines, and help you make your techcomm\nproject accessibility-ready.\ \ Welcome to A11y for Tech Docs!

    \n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/inclusive-tech-docs-techcomm-meets-accessibility-rmatic + path: https://www.youtube.com/watch?v=RcjpBNIKlf8 series: Write the Docs EU series_slug: eu slug: inclusive-tech-docs-techcomm-meets-accessibility-rmatic @@ -404,7 +404,7 @@ \ future is bright if we pay attention to our new opportunities instead\nof that\ \ nagging voice in our heads.

    \n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/imposter-no-more-how-tech-writers-can-shed-self-doubt-embrace-uncertainty-and-surf-the-upcoming-swerve-in-technical-documentation-rmacnamara + path: https://www.youtube.com/watch?v=pg_Y9hUt2dg series: Write the Docs EU series_slug: eu slug: imposter-no-more-how-tech-writers-can-shed-self-doubt-embrace-uncertainty-and-surf-the-upcoming-swerve-in-technical-documentation-rmacnamara @@ -430,7 +430,7 @@ \ same time, the\nexperience should be as engaging and pleasant as possible. Building\ \ a Visual\nDocumentation Language serves to reach this goal.

    \n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/visual-documentation-language-sheinen + path: https://www.youtube.com/watch?v=njXdQmcSX-k series: Write the Docs EU series_slug: eu slug: visual-documentation-language-sheinen @@ -452,7 +452,7 @@ \ walk hand\nin hand and to improve the communication between both humans and\n\ machines.

    \n" event: Write the Docs EU 2015 - path: conf/eu/2015/videos/writing-for-what-matters-writing-for-thinking-znemec + path: https://www.youtube.com/watch?v=bKOnRVb_0TE series: Write the Docs EU series_slug: eu slug: writing-for-what-matters-writing-for-thinking-znemec @@ -465,7 +465,7 @@ year: '2015' youtubeId: bKOnRVb_0TE - event: Write the Docs EU 2015 - path: conf/eu/2015/videos/lightning-talks-day-one + path: https://www.youtube.com/watch?v=RGl6bu0_NFc series: Write the Docs EU series_slug: eu slug: lightning-talks-day-one @@ -473,7 +473,7 @@ year: '2015' youtubeId: RGl6bu0_NFc - event: Write the Docs EU 2015 - path: conf/eu/2015/videos/lightning-talks-day-two + path: https://www.youtube.com/watch?v=g6hQdc9GOlQ series: Write the Docs EU series_slug: eu slug: lightning-talks-day-two diff --git a/docs/_data/2015.na.speakers.yaml b/docs/_data/2015.na.speakers.yaml index 4653981a94..788a9c7f3f 100644 --- a/docs/_data/2015.na.speakers.yaml +++ b/docs/_data/2015.na.speakers.yaml @@ -3,7 +3,7 @@ \ One thing endures: the writer's goal of communicating to understanding. It\u2019\ \ s not as easy as it sounds. Because we are all Abbott and Costello.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/keynote-we-are-all-abbott-and-costello-maria-riefer-johnston + path: https://www.youtube.com/watch?v=1yhyxuu_oWw series: Write the Docs NA series_slug: na slug: keynote-we-are-all-abbott-and-costello-maria-riefer-johnston @@ -22,7 +22,7 @@ to ease improvement and federation to ease sharing, we have once again uncovered a simpler and more powerful internet.

    event: Write the Docs NA 2015 - path: conf/na/2015/videos/keynote-the-federated-wiki-ward-cunningham + path: https://www.youtube.com/watch?v=3nB8ml6UowE series: Write the Docs NA series_slug: na slug: keynote-the-federated-wiki-ward-cunningham @@ -50,7 +50,7 @@ clear writing across not just your documentation, but your headlines and error messages in your API.

    event: Write the Docs NA 2015 - path: conf/na/2015/videos/how-to-write-documentation-for-people-that-don-t-read-kburke + path: https://www.youtube.com/watch?v=sQP_hUNCrcE series: Write the Docs NA series_slug: na slug: how-to-write-documentation-for-people-that-don-t-read-kburke @@ -76,7 +76,7 @@ \ fellow writers, and senior leadership, making us fall in love again with our\ \ roles as documentarians.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/documentation-disrupted-how-two-technical-writers-changed-google-engineering-culture-built-a-team-made-powerful-friends-and-got-their-mojo-back-rmacnamara + path: https://www.youtube.com/watch?v=EnB8GtPuauw series: Write the Docs NA series_slug: na slug: documentation-disrupted-how-two-technical-writers-changed-google-engineering-culture-built-a-team-made-powerful-friends-and-got-their-mojo-back-rmacnamara @@ -103,7 +103,7 @@ \ By recognizing that fact, and opening up space in your work life for creativity,\ \ you can have an even bigger impact and a more fulfilling career.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/elevating-the-hedgehog-creativity-in-tech-writing-tfranko + path: https://www.youtube.com/watch?v=jwN2aAq4wGw series: Write the Docs NA series_slug: na slug: elevating-the-hedgehog-creativity-in-tech-writing-tfranko @@ -140,7 +140,7 @@ \ to achieve this, as well as things we\u2019re still working on. I\u2019ll leave\ \ space for discussion so we can all share ideas and successes.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/entry-points-and-guide-posts-helping-new-contributors-find-their-way-jswisher + path: https://www.youtube.com/watch?v=VG-uvJDBTdM series: Write the Docs NA series_slug: na slug: entry-points-and-guide-posts-helping-new-contributors-find-their-way-jswisher @@ -168,7 +168,7 @@ \ building what we want to have in the end.

    Continuous improvement can\ \ have a victory condition, if we build it.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/success-is-more-than-not-failing-hwaterhouse + path: https://www.youtube.com/watch?v=mkyeF2YSRl8 series: Write the Docs NA series_slug: na slug: success-is-more-than-not-failing-hwaterhouse @@ -190,7 +190,7 @@ \ curve as much as possible for these readers, and it can do that by being much\ \ more intimate about its relationship with them.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/a-developers-approach-to-documentation-from-passive-to-dynamic-gkoberger + path: https://www.youtube.com/watch?v=5lw8RFy3YNA series: Write the Docs NA series_slug: na slug: a-developers-approach-to-documentation-from-passive-to-dynamic-gkoberger @@ -216,7 +216,7 @@ content through CI and automated tests
  • How we incorporate feedback from our users
    • event: Write the Docs NA 2015 - path: conf/na/2015/videos/how-github-uses-github-to-document-github-gtorikian + path: https://www.youtube.com/watch?v=s46m8H4BrrE series: Write the Docs NA series_slug: na slug: how-github-uses-github-to-document-github-gtorikian @@ -250,7 +250,7 @@ \ who is witnessing this documentation culture change, one conversation at a time.\ \ Wearing many hats can be exhilarating and rewarding.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/what-can-brownfield-do-for-you-mnishiyama + path: https://www.youtube.com/watch?v=3X8xyfkRmO4 series: Write the Docs NA series_slug: na slug: what-can-brownfield-do-for-you-mnishiyama @@ -279,7 +279,7 @@ \ pilot programs. We\u2019ve clarified our documentation and added test cases\ \ numerous times based on customer pain points.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/writer-meet-tester-jbleyle-alouie-arthur-louie + path: https://www.youtube.com/watch?v=W5Un3r-vG_I series: Write the Docs NA series_slug: na slug: writer-meet-tester-jbleyle-alouie-arthur-louie @@ -300,7 +300,7 @@ \ only 3 reasons I use words in user interfaces, how I find the right words, and\ \ how I increase engagement by respecting people\u2019 intent.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/keep-em-playing-tpodmajersky + path: https://www.youtube.com/watch?v=AMRfkcmyc40 series: Write the Docs NA series_slug: na slug: keep-em-playing-tpodmajersky @@ -337,7 +337,7 @@ \ like PeopleSoft, Oracle, and Intuit. He's currently a writer for Splunk, a leader\ \ in the machine data analytics sector.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/let-s-tell-a-story-scenario-based-documentation-mness + path: https://www.youtube.com/watch?v=3hneCmLYWjc series: Write the Docs NA series_slug: na slug: let-s-tell-a-story-scenario-based-documentation-mness @@ -367,7 +367,7 @@ how to make your stakeholders happier as your documentation base grows with the organization. event: Write the Docs NA 2015 - path: conf/na/2015/videos/designing-information-for-growth-mdevoto + path: https://www.youtube.com/watch?v=-y4itLMwX8g series: Write the Docs NA series_slug: na slug: designing-information-for-growth-mdevoto @@ -407,7 +407,7 @@ \ the writing process is itself a powerful tool to root out hidden assumptions\ \ and errors in thinking.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/a-brief-history-of-math-writing-symbol-structure-and-proof-ehoffmann-aroman-alfonso-roman + path: https://www.youtube.com/watch?v=3PbkglMkzS0 series: Write the Docs NA series_slug: na slug: a-brief-history-of-math-writing-symbol-structure-and-proof-ehoffmann-aroman-alfonso-roman @@ -445,7 +445,7 @@ \ in tandem with code deployment are among the experiments we\u2019re attempting\ \ to get better at this new world." event: Write the Docs NA 2015 - path: conf/na/2015/videos/tech-writing-in-a-continuous-deployment-world-cburwinkle + path: https://www.youtube.com/watch?v=Bsod_z9OKQY series: Write the Docs NA series_slug: na slug: tech-writing-in-a-continuous-deployment-world-cburwinkle @@ -473,7 +473,7 @@ \ a lot of hard work. But the people you'll meet and the contacts that you'll\ \ make can reward you and your company in other ways.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/start-your-own-write-the-docs-meetup-group-mjang + path: https://www.youtube.com/watch?v=ZwQ8Kd48d0w series: Write the Docs NA series_slug: na slug: start-your-own-write-the-docs-meetup-group-mjang @@ -510,7 +510,7 @@ \ ever with the development teams. Now our users get twice the cake: better features\ \ and better docs!" event: Write the Docs NA 2015 - path: conf/na/2015/videos/user-story-driven-docs-jfernandes + path: https://www.youtube.com/watch?v=MRnZFVCirQM series: Write the Docs NA series_slug: na slug: user-story-driven-docs-jfernandes @@ -539,7 +539,7 @@ \ failures, and how each of the seven (and a half) rules has taught us what it\ \ means to write Fastly.

    " event: Write the Docs NA 2015 - path: conf/na/2015/videos/the-making-of-writing-black-belts-how-martial-arts-philosophy-forged-an-ad-hoc-writing-team-that-writes-great-docs-gwalli + path: https://www.youtube.com/watch?v=4PP2xBsMWKw series: Write the Docs NA series_slug: na slug: the-making-of-writing-black-belts-how-martial-arts-philosophy-forged-an-ad-hoc-writing-team-that-writes-great-docs-gwalli diff --git a/docs/_data/2016.eu.speakers.yaml b/docs/_data/2016.eu.speakers.yaml index 8199d9beda..58bea3add3 100644 --- a/docs/_data/2016.eu.speakers.yaml +++ b/docs/_data/2016.eu.speakers.yaml @@ -11,7 +11,7 @@ and how to balance being firm and keeping control of your product with being diplomatic and being able to sleep at night.

    event: Write the Docs EU 2016 - path: conf/eu/2016/videos/feedback-handling-community-wrangling-panhandling-chris-mills + path: https://www.youtube.com/watch?v=VabBD1MWdE8 series: Write the Docs EU series_slug: eu slug: feedback-handling-community-wrangling-panhandling-chris-mills @@ -47,7 +47,7 @@ show you how documentation really can be a team effort, even if you stand alone in your company as the sole owner of the docs.

    event: Write the Docs EU 2016 - path: conf/eu/2016/videos/documentoring-growing-a-love-the-docs-community-david-oliver + path: https://www.youtube.com/watch?v=5LRagMvlEuk series: Write the Docs EU series_slug: eu slug: documentoring-growing-a-love-the-docs-community-david-oliver @@ -75,7 +75,7 @@ everyone can use for screenshots?
  • Some examples of really useless screenshots.
    • event: Write the Docs EU 2016 - path: conf/eu/2016/videos/when-bad-screenshots-happen-to-good-writers-swapnil-ogale + path: https://www.youtube.com/watch?v=SU2mRSaa1yQ series: Write the Docs EU series_slug: eu slug: when-bad-screenshots-happen-to-good-writers-swapnil-ogale @@ -105,7 +105,7 @@ hope that everyone will have learnt a lot from each other and realize that we're all trying to achieve the same thing(s).

    event: Write the Docs EU 2016 - path: conf/eu/2016/videos/beyond-software-learning-from-other-technical-writers-chris-ward + path: https://www.youtube.com/watch?v=pfLw8WmQ3nM series: Write the Docs EU series_slug: eu slug: beyond-software-learning-from-other-technical-writers-chris-ward @@ -139,7 +139,7 @@ \ and main findings of our studies, I will also discuss implications the results\ \ may have regarding the contents, structure and design of API documentation.

    " event: Write the Docs EU 2016 - path: conf/eu/2016/videos/api-documentation-exploring-the-information-needs-of-software-developers-michael-meng + path: https://www.youtube.com/watch?v=soQSOBwiXdA series: Write the Docs EU series_slug: eu slug: api-documentation-exploring-the-information-needs-of-software-developers-michael-meng @@ -168,7 +168,7 @@ \ some writing tools, habits, and methods that may be worth to take a chance.

    \ \

    I would like to present what I've learned during my journey so far.

    " event: Write the Docs EU 2016 - path: conf/eu/2016/videos/writing-as-a-non-native-speaker-istvan-zoltan-szabo + path: https://www.youtube.com/watch?v=KWqhW4Guo5k series: Write the Docs EU series_slug: eu slug: writing-as-a-non-native-speaker-istvan-zoltan-szabo @@ -192,7 +192,7 @@ of the community, how documentarians usually start working in this field and give an overview of the most supported practises, tools, languages and skills.

    event: Write the Docs EU 2016 - path: conf/eu/2016/videos/poll-the-docs-kata-nagygyorgy + path: https://www.youtube.com/watch?v=nXEpyO6tNX8 series: Write the Docs EU series_slug: eu slug: poll-the-docs-kata-nagygyorgy @@ -227,7 +227,7 @@ \ distinguishes a checklist from a to-do list to developing checklist habits,\ \ you\u2019ll learn how to use checklists to help you write the docs.

    " event: Write the Docs EU 2016 - path: conf/eu/2016/videos/checklist-the-docs-daniel-beck + path: https://www.youtube.com/watch?v=mltBPPGsuTg series: Write the Docs EU series_slug: eu slug: checklist-the-docs-daniel-beck @@ -257,7 +257,7 @@ \ good reading material.\nThis talk will draw on examples from both popular fiction\ \ and documentation out in the world today.

    " event: Write the Docs EU 2016 - path: conf/eu/2016/videos/what-writing-fiction-teaches-you-about-writing-documentation-thursday-bram + path: https://www.youtube.com/watch?v=HaWWcJp2yo4 series: Write the Docs EU series_slug: eu slug: what-writing-fiction-teaches-you-about-writing-documentation-thursday-bram @@ -283,7 +283,7 @@ \ The talk closes with a comparison of classical \u201Eswagger-like\u201C API-documentation\ \ with the presented approach.

    " event: Write the Docs EU 2016 - path: conf/eu/2016/videos/using-meaningful-names-to-improve-api-documentation-jan-christian-krause + path: https://www.youtube.com/watch?v=YOBVWfmRHzc series: Write the Docs EU series_slug: eu slug: using-meaningful-names-to-improve-api-documentation-jan-christian-krause @@ -314,7 +314,7 @@ \ use the glorious data that support is already collecting\n \xB7 the\ \ metrics that matter for support-led user assistance

    " event: Write the Docs EU 2016 - path: conf/eu/2016/videos/documentarians-and-support-work-better-together-sarah-chambers + path: https://www.youtube.com/watch?v=qBpwoQftxcA series: Write the Docs EU series_slug: eu slug: documentarians-and-support-work-better-together-sarah-chambers @@ -344,7 +344,7 @@ choosing appropriate standards and prioritizing correctly. Don't let the perfect be the enemy of the good.

    event: Write the Docs EU 2016 - path: conf/eu/2016/videos/pretty-hurts-why-better-trumps-best-riona-macnamara + path: https://www.youtube.com/watch?v=NyFNrInlADs series: Write the Docs EU series_slug: eu slug: pretty-hurts-why-better-trumps-best-riona-macnamara @@ -375,7 +375,7 @@ \ quality feature documentation, getting out those blog posts and showing-off\ \ our lovely heap of Clojure*.

    *Crate is written in Java.

    " event: Write the Docs EU 2016 - path: conf/eu/2016/videos/postulating-the-backlog-laxative-paul-adams + path: https://www.youtube.com/watch?v=MD-RwSw-NGA series: Write the Docs EU series_slug: eu slug: postulating-the-backlog-laxative-paul-adams @@ -405,7 +405,7 @@ \ revision strategies that this approach suggests are especially useful for anyone\ \ who\u2019s writing, editing, or optimizing content for use at scale.

    " event: Write the Docs EU 2016 - path: conf/eu/2016/videos/information-micro-architecture-grammar-syntax-and-cognitive-rhetoric-rory-tanner + path: https://www.youtube.com/watch?v=GuAECnt4eJI series: Write the Docs EU series_slug: eu slug: information-micro-architecture-grammar-syntax-and-cognitive-rhetoric-rory-tanner @@ -434,7 +434,7 @@ electrical, manufacturing), travel, and developing one's photography skills -- and saying goodbye to capturing screenshots.

    event: Write the Docs EU 2016 - path: conf/eu/2016/videos/operations-technical-writing-for-data-centers-joan-wendt + path: https://www.youtube.com/watch?v=4AwmQmWK7Ys series: Write the Docs EU series_slug: eu slug: operations-technical-writing-for-data-centers-joan-wendt @@ -464,7 +464,7 @@ \ away with great examples of voice and tone wins (and fails), and practical tips\ \ about how to create voicify guidelines for writers and non-writers alike.

    " event: Write the Docs EU 2016 - path: conf/eu/2016/videos/watch-that-tone-creating-an-information-experience-in-the-atlassian-voice-sarah-karp + path: https://www.youtube.com/watch?v=MeyKS4LwTds series: Write the Docs EU series_slug: eu slug: watch-that-tone-creating-an-information-experience-in-the-atlassian-voice-sarah-karp @@ -487,7 +487,7 @@ \
      \n
    • Increase project visibility
      • \n
    • Simplify peer reviews
      • \n\ \
    • Make bots do the scutwork
      • \n
    • Write more docs
      • \n
    " event: Write the Docs EU 2016 - path: conf/eu/2016/videos/delivering-high-velocity-docs-that-keep-pace-with-rapid-release-cycles-rachel-whitton + path: https://www.youtube.com/watch?v=dHdBsNxtKeI series: Write the Docs EU series_slug: eu slug: delivering-high-velocity-docs-that-keep-pace-with-rapid-release-cycles-rachel-whitton @@ -525,7 +525,7 @@ \ can truly assist.
  • Reviewing and line/copy editing. Because you wouldn't\ \ do any less for code, right?
    • " event: Write the Docs EU 2016 - path: conf/eu/2016/videos/docs-as-code-the-missing-manual-margaret-eker-jennifer-rondeau + path: https://www.youtube.com/watch?v=JvRd7MmAxPw series: Write the Docs EU series_slug: eu slug: docs-as-code-the-missing-manual-margaret-eker-jennifer-rondeau diff --git a/docs/_data/2016.na.speakers.yaml b/docs/_data/2016.na.speakers.yaml index bd9edc576c..cf192bf671 100644 --- a/docs/_data/2016.na.speakers.yaml +++ b/docs/_data/2016.na.speakers.yaml @@ -60,7 +60,7 @@ \ and the day-to-day details (how we work across teams to get useful information\ \ online).

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/technical-writing-as-public-service-working-on-open-source-in-government-britta-gustafson + path: https://www.youtube.com/watch?v=oAxPs_e8oPk series: Write the Docs NA series_slug: na slug: technical-writing-as-public-service-working-on-open-source-in-government-britta-gustafson @@ -97,7 +97,7 @@ \ to me and what I hope we're beginning to see in the tech comm world.\n\ " event: Write the Docs NA 2016 - path: conf/na/2016/videos/atlassian-my-information-experience-adventure-daniel-stevens + path: https://www.youtube.com/watch?v=kMSGYbWXxgE series: Write the Docs NA series_slug: na slug: atlassian-my-information-experience-adventure-daniel-stevens @@ -127,7 +127,7 @@ \ and measure how they change as you add more documentation\n
  • Have them\ \ write!
    • \n" event: Write the Docs NA 2016 - path: conf/na/2016/videos/two-great-teams-that-work-better-together-bridging-the-gap-between-documentation-and-customer-support-neal-kaplan + path: https://www.youtube.com/watch?v=HIvehEUKDfk series: Write the Docs NA series_slug: na slug: two-great-teams-that-work-better-together-bridging-the-gap-between-documentation-and-customer-support-neal-kaplan @@ -163,7 +163,7 @@ \ human voice can improve not only the reader\u2019s experience, but your own\ \ experience as a writer as well!

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/documentation-with-human-connection-hannah-gilberg + path: https://www.youtube.com/watch?v=K5eqNcjNvgU series: Write the Docs NA series_slug: na slug: documentation-with-human-connection-hannah-gilberg @@ -192,7 +192,7 @@ \ as an engineering lead and manager who has pushed to bring writing documentation\ \ into the internal culture and practices of a startup's engineering organization.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/move-fast-and-document-things-hard-won-lessons-in-building-documentation-culture-in-startups-ruthie-bendor + path: https://www.youtube.com/watch?v=INpqcITkXcI series: Write the Docs NA series_slug: na slug: move-fast-and-document-things-hard-won-lessons-in-building-documentation-culture-in-startups-ruthie-bendor @@ -218,7 +218,7 @@ \ create the just enough documentation, just in time. This presentation covers\ \ how we created this process, how we\u2019ve refined it and its success.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/just-in-time-documentation-employing-agile-methodology-to-create-living-documentation-brianne-hillmer + path: https://www.youtube.com/watch?v=FYNAqlQB9U4 series: Write the Docs NA series_slug: na slug: just-in-time-documentation-employing-agile-methodology-to-create-living-documentation-brianne-hillmer @@ -245,7 +245,7 @@ \ where I'm still learning about the product, the users, and the best way to ship\ \ documentation.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/7-values-of-effective-tech-writing-teams-joao-fernandes + path: https://www.youtube.com/watch?v=ra8nHK5wDXM series: Write the Docs NA series_slug: na slug: 7-values-of-effective-tech-writing-teams-joao-fernandes @@ -269,7 +269,7 @@ \ open-source software, and what to consider if you adapt this model for your\ \ community.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/how-to-publish-wild-caught-articles-sharon-campbell + path: https://www.youtube.com/watch?v=rCIdatJX7J0 series: Write the Docs NA series_slug: na slug: how-to-publish-wild-caught-articles-sharon-campbell @@ -307,7 +307,7 @@ \ you're new to the genre or a README connoisseur, you'll learn a process to write\ \ a README that works for you and your audience.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/write-the-readable-readme-daniel-beck + path: https://www.youtube.com/watch?v=2dAK42B7qtw series: Write the Docs NA series_slug: na slug: write-the-readable-readme-daniel-beck @@ -333,7 +333,7 @@ \ future, and discuss where these tools are going, as well as the implications\ \ for technical documentation.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/code-the-docs-interactive-document-environments-tim-nugent-paris-buttfield-addison + path: https://www.youtube.com/watch?v=kfqlRzDq4MA series: Write the Docs NA series_slug: na slug: code-the-docs-interactive-document-environments-tim-nugent-paris-buttfield-addison @@ -365,7 +365,7 @@ \ can understand and would want to read. More readers = more users = perhaps more\ \ contributors!

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/writing-so-your-words-are-read-tracy-osborn + path: https://www.youtube.com/watch?v=8LiV759Bje0 series: Write the Docs NA series_slug: na slug: writing-so-your-words-are-read-tracy-osborn @@ -395,7 +395,7 @@ \ frustration and fear.\n\n

    App copy is documentation for people who\ \ don\u2019t know your knowledge base exists.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/copy-that-helping-your-users-succeed-with-effective-product-copy-sarah-day + path: https://www.youtube.com/watch?v=M_Q1RO0ky2c series: Write the Docs NA series_slug: na slug: copy-that-helping-your-users-succeed-with-effective-product-copy-sarah-day @@ -423,7 +423,7 @@ \ inside Red Hat, as well as from over a decade in working with open source documentation\ \ communities.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/crossing-the-streams-enabling-collaboration-between-products-and-upstreams-shaun-mccance + path: https://www.youtube.com/watch?v=YlWD6YcUyXs series: Write the Docs NA series_slug: na slug: crossing-the-streams-enabling-collaboration-between-products-and-upstreams-shaun-mccance @@ -453,7 +453,7 @@ \ to invest time in crafting good reading material.

    \n

    This talk will draw\ \ on examples from both popular fiction and documentation out in the world today.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/what-writing-fiction-teaches-you-about-writing-documentation-thursday-bram + path: https://www.youtube.com/watch?v=UI9yD3_wgho series: Write the Docs NA series_slug: na slug: what-writing-fiction-teaches-you-about-writing-documentation-thursday-bram @@ -499,7 +499,7 @@ \ CSAT, and with it, we\u2019ll know that our audience is understanding our concise\ \ information in the best way possible.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/csat-what-s-that-betsy-roseberg + path: https://www.youtube.com/watch?v=Nmx9_GZNZF8 series: Write the Docs NA series_slug: na slug: csat-what-s-that-betsy-roseberg @@ -525,7 +525,7 @@ \ APIs when you\u2019re stuck with a publishing tool that might not be ideal for\ \ the task (Madcap Flare, for example).

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/so-you-need-to-document-an-api-allison-reinheimer-moore + path: https://www.youtube.com/watch?v=KSXL-BDoGOw series: Write the Docs NA series_slug: na slug: so-you-need-to-document-an-api-allison-reinheimer-moore @@ -552,7 +552,7 @@ \ for staying bold that I used as I gained more experience, and the secret I discovered\ \ about cultivating courage no matter where you are in your tech writing career.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/we-re-not-in-kansas-anymore-how-to-find-courage-while-following-the-technical-doc-road-christy-lutz + path: https://www.youtube.com/watch?v=C8pvvgwboJc series: Write the Docs NA series_slug: na slug: we-re-not-in-kansas-anymore-how-to-find-courage-while-following-the-technical-doc-road-christy-lutz @@ -581,7 +581,7 @@ \ team's experiment, while outlining a way you can design your own plan to balance\ \ any set of challenges and opportunities you're facing.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/continuous-annoyment-bringing-more-zen-to-a-hectic-writing-environment-tana-franko + path: https://www.youtube.com/watch?v=y8yhjVYXa20 series: Write the Docs NA series_slug: na slug: continuous-annoyment-bringing-more-zen-to-a-hectic-writing-environment-tana-franko @@ -610,7 +610,7 @@ \ source embeddable widget that makes it easy for non-technical authors to implement\ \ this paradigm.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/embed-the-docs-kristof-van-tomme + path: https://www.youtube.com/watch?v=bKdGDbROgoA series: Write the Docs NA series_slug: na slug: embed-the-docs-kristof-van-tomme @@ -638,7 +638,7 @@ \ hard, new stuff, this may be the 15 minutes during which you\u2019ll want to\ \ skip the hallway track.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/oops-i-became-an-engineer-tara-scherner-de-la-fuente + path: https://www.youtube.com/watch?v=b_Bo0sHEc7A series: Write the Docs NA series_slug: na slug: oops-i-became-an-engineer-tara-scherner-de-la-fuente @@ -668,7 +668,7 @@ \ of the problem is presented, a few of the challenges we found\nare discussed,\ \ and the final technical solution is described.

    " event: Write the Docs NA 2016 - path: conf/na/2016/videos/accessible-math-on-the-web-a-server-client-solution-tim-arnold + path: https://www.youtube.com/watch?v=_tYVqcdqcBM series: Write the Docs NA series_slug: na slug: accessible-math-on-the-web-a-server-client-solution-tim-arnold diff --git a/docs/_data/2017.eu.speakers.yaml b/docs/_data/2017.eu.speakers.yaml index 9080556c33..ed07bcc041 100644 --- a/docs/_data/2017.eu.speakers.yaml +++ b/docs/_data/2017.eu.speakers.yaml @@ -30,7 +30,7 @@

  • How can documentarians and developers work together to name things better?

    • " event: Write the Docs EU 2017 - path: conf/eu/2017/videos/even-naming-this-talk-is-hard-ruthie-bendor + path: https://www.youtube.com/watch?v=JuI6NUbEzDw series: Write the Docs EU series_slug: eu slug: even-naming-this-talk-is-hard-ruthie-bendor @@ -72,7 +72,7 @@ \ build demand within the company for further \u201Cgetting started\u201D\ \ content

    \n" event: Write the Docs EU 2017 - path: conf/eu/2017/videos/you-never-get-a-second-chance-to-make-a-first-impression-writing-great-getting-started-documentation-tim-rogers + path: https://www.youtube.com/watch?v=wqC88GNujWQ series: Write the Docs EU series_slug: eu slug: you-never-get-a-second-chance-to-make-a-first-impression-writing-great-getting-started-documentation-tim-rogers @@ -96,7 +96,7 @@ \ documentation, and why I think that GraphQL is a boon for technical writers,\ \ developers, and end users.

    " event: Write the Docs EU 2017 - path: conf/eu/2017/videos/finally-trustworthy-and-sensible-api-documentation-with-graphql-garen-torikian + path: https://www.youtube.com/watch?v=aJk99MSVj0Y series: Write the Docs EU series_slug: eu slug: finally-trustworthy-and-sensible-api-documentation-with-graphql-garen-torikian @@ -135,7 +135,7 @@ \ or wondering how better docs can help your OSS efforts succeed, you might\ \ find some help here.

    " event: Write the Docs EU 2017 - path: conf/eu/2017/videos/telling-a-great-story-on-github-lauri-apple + path: https://www.youtube.com/watch?v=9fq3-U9PKAA series: Write the Docs EU series_slug: eu slug: telling-a-great-story-on-github-lauri-apple @@ -174,7 +174,7 @@ \ and poorly-understood aspects of documentation that will make your software\ \ projects and teams more successful.

    " event: Write the Docs EU 2017 - path: conf/eu/2017/videos/the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida + path: https://www.youtube.com/watch?v=p0PPtdRHG6M series: Write the Docs EU series_slug: eu slug: the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida @@ -203,7 +203,7 @@ about the words we use with our coworkers. Let''s talk about how we can all make diversity a daily practice at work, not just a hiring problem.

    ' event: Write the Docs EU 2017 - path: conf/eu/2017/videos/sticks-stones-microaggressions-inclusive-language-at-work-cory-williamson-cardneau + path: https://www.youtube.com/watch?v=lXXuQQ9xtPc series: Write the Docs EU series_slug: eu slug: sticks-stones-microaggressions-inclusive-language-at-work-cory-williamson-cardneau @@ -312,7 +312,7 @@ \ contractions, and even emojis? \n\u2022 What are the implications of this\ \ evolution on localization?

    " event: Write the Docs EU 2017 - path: conf/eu/2017/videos/aw-snap-the-docs-they-are-a-changin-with-apologies-to-bob-dylan-kate-wilcox + path: https://www.youtube.com/watch?v=DYgw6xcpDmE series: Write the Docs EU series_slug: eu slug: aw-snap-the-docs-they-are-a-changin-with-apologies-to-bob-dylan-kate-wilcox @@ -341,7 +341,7 @@ \ essays, documentation \u2014 that we can transform in physical books, e-books,\ \ interactive web pages etc.

    " event: Write the Docs EU 2017 - path: conf/eu/2017/videos/writing-a-book-in-2017-thomas-parisot + path: https://www.youtube.com/watch?v=p2eAXLR3OOk series: Write the Docs EU series_slug: eu slides: https://oncletom.io/talks/2017/writethedocs/ @@ -366,7 +366,7 @@ of your docs depends on things you are never told. This talk is about reading your stakeholders and deducing the ultimate requirements.

    event: Write the Docs EU 2017 - path: conf/eu/2017/videos/requirements-that-you-didn-t-know-were-there-lesia-zasadna + path: https://www.youtube.com/watch?v=3oklMXaGA3Y slides: https://www.slideshare.net/LesiaZasadna/requirements-that-you-didnt-know-were-there-write-the-docs-europe-2017 series: Write the Docs EU series_slug: eu @@ -417,7 +417,7 @@

    In summary, our work typically appears on one of the most dynamic platforms (the web) that has ever existed, let''s all do more with it!

    ' event: Write the Docs EU 2017 - path: conf/eu/2017/videos/documentation-beyond-words-chris-ward + path: https://www.youtube.com/watch?v=lTYvWjS1nHw series: Write the Docs EU series_slug: eu slug: documentation-beyond-words-chris-ward @@ -446,7 +446,7 @@ \ and hear more about my main takeaways regarding documentation in general\ \ and the experiences with my team in particular.

    " event: Write the Docs EU 2017 - path: conf/eu/2017/videos/an-alien-looking-from-the-outside-in-main-takeaways-after-one-year-in-documentation-meike-chabowski + path: https://www.youtube.com/watch?v=y4UyU4XIn5c series: Write the Docs EU series_slug: eu slug: an-alien-looking-from-the-outside-in-main-takeaways-after-one-year-in-documentation-meike-chabowski @@ -477,7 +477,7 @@ \ announcement to your service\u2019s last day, you\u2019ll learn how to say\ \ goodbye in a way that\u2019s good for you and your soon-to-be-former users.

    " event: Write the Docs EU 2017 - path: conf/eu/2017/videos/deprecate-and-destroy-documenting-your-software-s-last-days-daniel-d-beck + path: https://www.youtube.com/watch?v=XWNw3TgbGLg series: Write the Docs EU series_slug: eu slides: https://ddbeck.com/wtdeu2017/ @@ -509,7 +509,7 @@ title: 'Tech Writers Without Borders: Making the world a better place, one (numbered) step at a time' slides: https://speakerdeck.com/sculshaw/making-the-world-a-better-place-one-numbered-step-at-a-time event: Write the Docs EU 2017 - path: conf/eu/2017/videos/tech-writers-without-borders-making-the-world-a-better-place-one-numbered-step-at-a-time-stuart-culshaw + path: https://www.youtube.com/watch?v=MgS1WuOcK4o series: Write the Docs EU series_slug: eu slug: tech-writers-without-borders-making-the-world-a-better-place-one-numbered-step-at-a-time-stuart-culshaw @@ -577,7 +577,7 @@ and wants to know how documentation can help newcomers and more experienced users use your code and to encourage them to engage in the community.

    ' event: Write the Docs EU 2017 - path: conf/eu/2017/videos/hi-my-name-is-readme-raphael-pierzina + path: https://www.youtube.com/watch?v=0z0jquYos90 series: Write the Docs EU series_slug: eu slides: https://speakerdeck.com/hackebrot/hi-my-name-is-readme-writethedocs-2017 @@ -622,7 +622,7 @@ ' event: Write the Docs EU 2017 - path: conf/eu/2017/videos/a-content-manager-s-guide-to-crowdsourcing-the-docs-becky-todd + path: https://www.youtube.com/watch?v=BnWmPulCNhA series: Write the Docs EU series_slug: eu slides: https://www.slideshare.net/BeckyTodd3/content-managers-guide-to-crowdsourcing-the-docs @@ -652,7 +652,7 @@ \ that you can implement design critique guidelines into your own review process\ \ to make feedback painless.

    " event: Write the Docs EU 2017 - path: conf/eu/2017/videos/you-have-already-succeeded-design-critique-guidelines-make-feedback-easier-2-0-christy-lutz + path: https://www.youtube.com/watch?v=DOuRgFP4NMQ series: Write the Docs EU series_slug: eu slides: http://canncrochet.com/filter/articles/Presentations-1 diff --git a/docs/_data/2017.na.speakers.yaml b/docs/_data/2017.na.speakers.yaml index ddf06833e6..854754a64a 100644 --- a/docs/_data/2017.na.speakers.yaml +++ b/docs/_data/2017.na.speakers.yaml @@ -140,7 +140,7 @@ \ strategies\nthat I have used successfully in my workplace and they can work\ \ for you too.

    \n" event: Write the Docs NA 2017 - path: conf/na/2017/videos/everyone-s-a-player-in-a-mid-90s-mud-kenzie-woodbridge + path: https://www.youtube.com/watch?v=BiYSJ5dkoM0 series: Write the Docs NA series_slug: na slides: https://docs.google.com/presentation/d/16lt-az4HyfWOg4k-HxbH2rhfmC5q6dC9Nuy0Exb3VYU @@ -210,7 +210,7 @@ ' event: Write the Docs NA 2017 - path: conf/na/2017/videos/testing-it-s-not-just-for-code-anymore-lyzi-diamond + path: https://www.youtube.com/watch?v=e1_MMEr4kNU series: Write the Docs NA series_slug: na slug: testing-it-s-not-just-for-code-anymore-lyzi-diamond @@ -324,7 +324,7 @@ ' event: Write the Docs NA 2017 - path: conf/na/2017/videos/building-navigation-for-your-doc-site-5-best-practices-tom-johnson + path: https://www.youtube.com/watch?v=w-kEmsLwPDE series: Write the Docs NA series_slug: na slides: http://idratherbewriting.com/files/doc-navigation-wtd/index.html @@ -367,7 +367,7 @@ ' event: Write the Docs NA 2017 - path: conf/na/2017/videos/you-have-already-succeeded-design-critique-guidelines-make-feedback-easier-christy-lutz + path: https://www.youtube.com/watch?v=E_GyqG3Gd38 series: Write the Docs NA series_slug: na slides: http://canncrochet.com/Presentations-1 @@ -417,7 +417,7 @@ ' event: Write the Docs NA 2017 - path: conf/na/2017/videos/only-interesting-conversations-the-symbiotic-relationship-between-docs-and-support-matthew-buttler + path: https://www.youtube.com/watch?v=qXrX6hZO6V0 series: Write the Docs NA series_slug: na slides: https://docs.google.com/presentation/d/1JpyWi6uN-3zhM77ApzVz15jUw_8dckEh1Hs6dhsac2o/edit?usp=sharing @@ -494,7 +494,7 @@ ' event: Write the Docs NA 2017 - path: conf/na/2017/videos/error-messages-being-humble-human-and-helpful-will-make-users-happy-kate-voss + path: https://www.youtube.com/watch?v=gBBZUATL7Qo series: Write the Docs NA series_slug: na slides: https://docs.google.com/presentation/d/1gCgkaaXIFSLf3afRxEGNFwm0bPTcURcVQNuQj0QZDqQ/edit @@ -555,7 +555,7 @@ the impression after a good assignment test? What things should be asked during\n\ an interview?

    \n" event: Write the Docs NA 2017 - path: conf/na/2017/videos/interviewing-and-hiring-technical-writers-the-siberian-way-sam-faktorovich + path: https://www.youtube.com/watch?v=tcjLbCLcPTo series: Write the Docs NA series_slug: na slides: https://speakerdeck.com/factorized/hiring-technical-writers-the-siberian-way @@ -629,7 +629,7 @@ ' event: Write the Docs NA 2017 - path: conf/na/2017/videos/treating-documentation-like-code-a-practical-account-jodie-putrino + path: https://www.youtube.com/watch?v=Mzu-c-FoOdw series: Write the Docs NA series_slug: na slides: https://slides.com/jodieputrino/treating-docs-like-code @@ -710,7 +710,7 @@ ' event: Write the Docs NA 2017 - path: conf/na/2017/videos/no-community-members-were-harmed-in-the-making-of-this-doc-sprint-how-we-ran-a-48-hour-event-to-collect-community-wisdom-into-a-guidebook-for-newsroom-developers-ryan-pitts-lindsay-muscato + path: https://www.youtube.com/watch?v=08l9FGJOz5E series: Write the Docs NA series_slug: na slug: no-community-members-were-harmed-in-the-making-of-this-doc-sprint-how-we-ran-a-48-hour-event-to-collect-community-wisdom-into-a-guidebook-for-newsroom-developers-ryan-pitts-lindsay-muscato @@ -768,7 +768,7 @@ \ methods\nin more detail and show examples of content before and after crowdsourced\ \ minimalism.

    \n" event: Write the Docs NA 2017 - path: conf/na/2017/videos/the-wisdom-of-crowds-crowdsourcing-minimalism-in-an-open-organization-ingrid-towey + path: https://www.youtube.com/watch?v=s3Em8QSXyn8 series: Write the Docs NA series_slug: na slides: https://docs.google.com/presentation/d/1Yeql9FrRBgKU-QlRU-nblPJ9pfZKgoKcU8SW6SQ_UqI/edit?usp=sharing @@ -816,7 +816,7 @@ ' event: Write the Docs NA 2017 - path: conf/na/2017/videos/caring-systems-documentation-as-care-amelia-abreu + path: https://www.youtube.com/watch?v=quC7mJn8B_U series: Write the Docs NA series_slug: na slug: caring-systems-documentation-as-care-amelia-abreu @@ -851,7 +851,7 @@ docs architecture? - How do you iterate on, improve, and expand your docs,\n\ and harness contributors to do the same?

    \n" event: Write the Docs NA 2017 - path: conf/na/2017/videos/bootstrapping-docs-at-a-startup-jesse-seldess + path: https://www.youtube.com/watch?v=YLXNJXQyYoE series: Write the Docs NA series_slug: na slides: https://docs.google.com/presentation/d/1Sce3OtXMF2mUV11taCqNzXERdsFBtfdxBXYqs7EBI_k/edit?usp=sharing @@ -973,7 +973,7 @@ ' event: Write the Docs NA 2017 - path: conf/na/2017/videos/even-naming-this-talk-is-hard-ruthie-bendor + path: https://www.youtube.com/watch?v=RFfpkrbkvxc series: Write the Docs NA series_slug: na slides: https://www.slideshare.net/unruthless/even-naming-this-talk-is-hard @@ -1015,7 +1015,7 @@ \ information architecture, to deciding\nwhich content assets to prioritize,\ \ to refining the tone used throughout your\ndeveloper communications.

    \n" event: Write the Docs NA 2017 - path: conf/na/2017/videos/start-with-the-tasks-not-the-endpoints-sarah-hersh + path: https://www.youtube.com/watch?v=R8yjmtIWEKQ series: Write the Docs NA series_slug: na slides: https://docs.google.com/presentation/d/1I9FwgeRD0JvkikuQqf64fncvlK_YwxOpmDdoS1oSTQQ/pub?start=true&loop=false&delayms=60000#slide=id.p @@ -1075,7 +1075,7 @@ ' event: Write the Docs NA 2017 - path: conf/na/2017/videos/intelligent-documents-and-the-verifiability-crisis-in-science-tech-writing-and-life-carl-parker + path: https://www.youtube.com/watch?v=kOzQPpc-KDo series: Write the Docs NA series_slug: na slides: https://github.com/carljparker/wtd-2017-verifiable-crisis @@ -1138,7 +1138,7 @@ ' event: Write the Docs NA 2017 - path: conf/na/2017/videos/do-you-know-a-runbook-from-a-flip-book-how-sysadmins-use-documentation-andrea-longo + path: https://www.youtube.com/watch?v=QDxoqWpyzo8 series: Write the Docs NA series_slug: na slides: http://feorlen.org/wtd/index.html diff --git a/docs/_data/2018.australia.speakers.yaml b/docs/_data/2018.australia.speakers.yaml index 10502cbf39..2c4b6135df 100644 --- a/docs/_data/2018.australia.speakers.yaml +++ b/docs/_data/2018.australia.speakers.yaml @@ -13,7 +13,7 @@ \ and potentially blow the whistle on, potential disasters before they happen.

    " details: '' event: Write the Docs Australia 2018 - path: conf/australia/2018/videos/facebook-dynamite-uber-bombs-and-you-lana-brindley + path: https://www.youtube.com/watch?v=N13_FP2NkSk series: Write the Docs Australia series_slug: australia slug: facebook-dynamite-uber-bombs-and-you-lana-brindley @@ -39,7 +39,7 @@ \ to ensure that your content is presented to your reader in an optimized manner.

    \n" details: '' event: Write the Docs Australia 2018 - path: conf/australia/2018/videos/responsive-content-presenting-your-information-on-any-device-mike-hamilton + path: https://www.youtube.com/watch?v=z7KBdPyRb18 series: Write the Docs Australia series_slug: australia slug: responsive-content-presenting-your-information-on-any-device-mike-hamilton @@ -62,7 +62,7 @@ \ organisation?\n \n" details: '' event: Write the Docs Australia 2018 - path: conf/australia/2018/videos/the-art-of-consistency-creating-an-inhouse-style-guide-kristine-sihto + path: https://www.youtube.com/watch?v=IDLSiX9O0Lg series: Write the Docs Australia series_slug: australia slug: the-art-of-consistency-creating-an-inhouse-style-guide-kristine-sihto @@ -88,7 +88,7 @@ \ thing, technical writers are/can be great UX writers!

    " details: '' event: Write the Docs Australia 2018 - path: conf/australia/2018/videos/ux-writing-let-your-product-speak-abhay-chokshi + path: https://www.youtube.com/watch?v=TGdm-1vVLDw series: Write the Docs Australia series_slug: australia slug: ux-writing-let-your-product-speak-abhay-chokshi @@ -117,7 +117,7 @@ \ being updated when you move on.

    " details: '' event: Write the Docs Australia 2018 - path: conf/australia/2018/videos/making-yourself-redundant-on-day-one-internal-documentation-to-teach-the-next-hire-what-you-ve-learned-alexandra-perkins + path: https://www.youtube.com/watch?v=QYMUh55eXcY series: Write the Docs Australia series_slug: australia slug: making-yourself-redundant-on-day-one-internal-documentation-to-teach-the-next-hire-what-you-ve-learned-alexandra-perkins @@ -169,7 +169,7 @@ \ you help your teammates to write better code.

    " details: '' event: Write the Docs Australia 2018 - path: conf/australia/2018/videos/good-code-bad-code-code-review-matthew-borden + path: https://www.youtube.com/watch?v=Mx4iRq-inm8 series: Write the Docs Australia series_slug: australia slug: good-code-bad-code-code-review-matthew-borden @@ -191,7 +191,7 @@ \ out of unwilling participants, in spite of themselves!

    " details: '' event: Write the Docs Australia 2018 - path: conf/australia/2018/videos/the-subtle-art-of-interrogation-nicola-nye + path: https://www.youtube.com/watch?v=HVdzjFeaM7k series: Write the Docs Australia series_slug: australia slug: the-subtle-art-of-interrogation-nicola-nye @@ -218,7 +218,7 @@ \ how far we have yet to go.

    " details: '' event: Write the Docs Australia 2018 - path: conf/australia/2018/videos/creating-experiences-with-information-daniel-stevens + path: https://www.youtube.com/watch?v=N_fUHIu9cl4 series: Write the Docs Australia series_slug: australia slug: creating-experiences-with-information-daniel-stevens @@ -240,7 +240,7 @@ \ to instigate massive change on multiple fronts.

    " details: '' event: Write the Docs Australia 2018 - path: conf/australia/2018/videos/backseat-content-strategy-laura-bailey + path: https://www.youtube.com/watch?v=omwamA30e_Y series: Write the Docs Australia series_slug: australia slug: backseat-content-strategy-laura-bailey @@ -265,7 +265,7 @@ \ documentation.

    " details: '' event: Write the Docs Australia 2018 - path: conf/australia/2018/videos/power-up-your-support-team-to-create-better-documentation-mathew-patterson + path: https://www.youtube.com/watch?v=8QrsSsSqddc series: Write the Docs Australia series_slug: australia slug: power-up-your-support-team-to-create-better-documentation-mathew-patterson @@ -309,7 +309,7 @@ \ and publishing of your own statically generated portfolio website\n " details: '' event: Write the Docs Australia 2018 - path: conf/australia/2018/videos/workshop-static-site-generators-what-why-and-how-jessica-parsons + path: https://www.youtube.com/watch?v=2RCqk-nEn90 series: Write the Docs Australia series_slug: australia slug: workshop-static-site-generators-what-why-and-how-jessica-parsons diff --git a/docs/_data/2018.portland.speakers.yaml b/docs/_data/2018.portland.speakers.yaml index 89f5c7de16..5767aa309c 100644 --- a/docs/_data/2018.portland.speakers.yaml +++ b/docs/_data/2018.portland.speakers.yaml @@ -8,7 +8,7 @@ and tutorials (and working with Swagger/OpenAPI), and give some examples of habits I had to un-learn, too!

    ' event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/what-writing-dictionaries-taught-me-about-writing-documentation-and-what-i-had-to-unlearn-erin-mckean + path: https://www.youtube.com/watch?v=O_xaiot6N7U series: Write the Docs PORTLAND series_slug: portland slug: what-writing-dictionaries-taught-me-about-writing-documentation-and-what-i-had-to-unlearn-erin-mckean @@ -33,7 +33,7 @@ \ user-friendly?\n
  • Do we even actually need FAQs?
    • \n\n

    (Caution:\ \ May contain opinions.)

    " event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/the-facts-about-faqs-ashleigh-rentz + path: https://www.youtube.com/watch?v=8_fHC0OUkmc series: Write the Docs PORTLAND series_slug: portland slug: the-facts-about-faqs-ashleigh-rentz @@ -58,7 +58,7 @@ \ set of interviews, and how we onboarded writers with strong skills and aptitude,\ \ but no real-world experience.

    " event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/starting-from-scratch-finding-and-hiring-junior-writers-sarah-day + path: https://www.youtube.com/watch?v=GiHZY8P4kpA series: Write the Docs PORTLAND series_slug: portland slug: starting-from-scratch-finding-and-hiring-junior-writers-sarah-day @@ -83,7 +83,7 @@ \ need to strategically get the right docs to the right people at the right time\u2014\ and learn a little bit more about their stakeholders along the way.

    \n" event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/audience-market-product-tips-for-strategic-api-documentation-planning-bob-watson + path: https://www.youtube.com/watch?v=ax_6cS3JHvY series: Write the Docs PORTLAND series_slug: portland slug: audience-market-product-tips-for-strategic-api-documentation-planning-bob-watson @@ -108,7 +108,7 @@
  • Use the power of storytelling.

    • There might even be a surprise bonus tip.

    " event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/7-essential-tips-for-the-enlightened-tech-writer-ted-hudek + path: https://www.youtube.com/watch?v=-lHKnF2EPd8 series: Write the Docs PORTLAND series_slug: portland slug: 7-essential-tips-for-the-enlightened-tech-writer-ted-hudek @@ -137,7 +137,7 @@ \ progress with great results, and I look forward to sharing our best policies\ \ and practices.

    " event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/making-your-code-examples-shine-larry-ullman + path: https://www.youtube.com/watch?v=td15D2BLa4c series: Write the Docs PORTLAND series_slug: portland slug: making-your-code-examples-shine-larry-ullman @@ -155,7 +155,7 @@

    This talk will explore principles and patterns of kind, effective editorial practice, and nuances of voice, civility, and clear communication, as they play out when working with a diverse distributed roster of authors, many of whom are non-native English speakers or first-time storytellers.

    I believe there’s as much appetite for diversity of voice and point of view in blogging about software development as there is in speaking about it at developer conferences. And I’ve got some observations to share about how we can cultivate that.

    " event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/not-the-docs-shepherding-a-developer-blog-of-many-voices-across-many-timezones-havi-hoffman + path: https://www.youtube.com/watch?v=GMEZv_KSsJE series: Write the Docs PORTLAND series_slug: portland slug: not-the-docs-content-and-voice-on-a-developer-blog-havi-hoffman @@ -186,7 +186,7 @@ \ other roles) can make the biggest difference to user experience, and through\ \ that to their organisations.

    " event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/who-writes-the-docs-beth-aitman + path: https://www.youtube.com/watch?v=eOC6rsizIvM series: Write the Docs PORTLAND series_slug: portland slug: who-writes-the-docs-beth-aitman @@ -213,7 +213,7 @@ \ work (legally!)\n
  • Options to present it that aren't just a series of\ \ email attachments

    • " event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/document-yourself-practical-tips-for-a-low-er-stress-portfolio-erin-grace + path: https://www.youtube.com/watch?v=3cXpf0Okmi8 series: Write the Docs PORTLAND series_slug: portland slug: document-yourself-practical-tips-for-a-low-er-stress-portfolio-erin-grace @@ -245,7 +245,7 @@ \ will require hard work, but a bit of advice can help you get started, stay motivated,\ \ and avoid pitfalls along the way.

    " event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/where-do-i-start-the-art-and-practice-of-documentation-triage-neal-kaplan + path: https://www.youtube.com/watch?v=2EzIe-3LBwQ series: Write the Docs PORTLAND series_slug: portland slug: where-do-i-start-the-art-and-practice-of-documentation-triage-neal-kaplan @@ -271,7 +271,7 @@ \ about what worked well for us, what ideas didn\u2019t pan out, and some of the\ \ documentation principles we\u2019re now sold on.

    \n" event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/building-empathy-driven-developer-documentation-kat-king + path: https://www.youtube.com/watch?v=_HCmFvxxKaQ series: Write the Docs PORTLAND series_slug: portland slug: building-empathy-driven-developer-documentation-kat-king @@ -294,7 +294,7 @@ \ sensitivity readings, and generally making sure you know how other people hear\ \ terms\n
  • teaching style across a team

    • " event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/what-they-don-t-tell-you-about-creating-new-style-guides-thursday-bram + path: https://www.youtube.com/watch?v=O1ZnCA-hZxQ series: Write the Docs PORTLAND series_slug: portland slug: what-they-don-t-tell-you-about-creating-new-style-guides-thursday-bram @@ -323,7 +323,7 @@ s all done, how to turn all that qualitative data into tangible content changes\ \ that have a genuine impact for users.

    " event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/research-like-you-re-wrong-lessons-from-user-research-gone-rogue-jen-lambourne + path: https://www.youtube.com/watch?v=aCNbVf9Id5Y series: Write the Docs PORTLAND series_slug: portland slug: research-like-you-re-wrong-lessons-from-user-research-gone-rogue-jen-lambourne @@ -348,7 +348,7 @@ and abstract "simplified UI (SUI)" representations. Which you use depends on your intent and message.

    event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/graphic-content-warning-the-pros-cons-and-alternatives-to-screenshots-steve-stegelin + path: https://www.youtube.com/watch?v=a6iAmLul4Gg series: Write the Docs PORTLAND series_slug: portland slug: graphic-content-warning-the-pros-cons-and-alternatives-to-screenshots-steve-stegelin @@ -382,7 +382,7 @@ documentation community about how we can make technical documentation more accessible, easier to reuse, and empowering.

    ' event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/rewrite-the-docs-field-notes-from-the-radical-it-department-camille-acey + path: https://www.youtube.com/watch?v=5WOM1ntJPFw series: Write the Docs PORTLAND series_slug: portland slug: rewrite-the-docs-field-notes-from-the-radical-it-department-camille-acey @@ -400,7 +400,7 @@

    Creating a great technical book takes more than a good idea. It also requires a knowledge of the market, to determine whether there's an audience willing to buy, or whether the space is too crowded to accept new entries. Publishers vary in their approach and target markets, so you need to determine which one will provide the best chance of success. Self-publishing is an option, but carries its own risks and benefits. Doing the setup work that you may not have thought about yet will help you create a proposal that will appeal to publishers, and will also make the writing process easier.

    Once you have a contract with a publisher, or have decided to self-publish, it's more than just a matter of putting the words in order. Finding the right environment, setting a schedule, and communicating with your editor are all critical to success. This session will explain how the process works, highlight the parts you may not know, and give you advice on how not to get overwhelmed by your project.

    " event: Write the Docs PORTLAND 2018 - path: conf/portland/2018/videos/writing-the-next-great-tech-book-brian-macdonald + path: https://www.youtube.com/watch?v=MKSXXKIe05o series: Write the Docs PORTLAND series_slug: portland slug: writing-the-next-great-tech-book-brian-macdonald diff --git a/docs/_data/2018.prague.speakers.yaml b/docs/_data/2018.prague.speakers.yaml index f064035412..f4699f812e 100644 --- a/docs/_data/2018.prague.speakers.yaml +++ b/docs/_data/2018.prague.speakers.yaml @@ -15,7 +15,7 @@ \ writing practices.

    " event: Write the Docs Prague 2018 name: Carolyn Stransky - path: conf/prague/2018/videos/a11y-friendly-documentation-carolyn-stransky + path: https://www.youtube.com/watch?v=SLUJG625Si0 series: Write the Docs Prague series_slug: prague slug: a11y-friendly-documentation-carolyn-stransky @@ -46,7 +46,7 @@ \ you\u2019ve fixed, and the suggestions you\u2019ve listened to\n" event: Write the Docs Prague 2018 name: Anne Edwards - path: conf/prague/2018/videos/learning-to-love-release-notes-anne-edwards + path: https://www.youtube.com/watch?v=L3yAD319DiU series: Write the Docs Prague series_slug: prague slug: learning-to-love-release-notes-anne-edwards @@ -100,7 +100,7 @@ \ own projects and workplaces on the road to Better Docs.

    " event: Write the Docs Prague 2018 name: Rowan Cota - path: conf/prague/2018/videos/a-year-in-the-life-of-the-better-docs-project-rowan-cota + path: https://www.youtube.com/watch?v=P3NL-Mms4-M series: Write the Docs Prague series_slug: prague slug: a-year-in-the-life-of-the-better-docs-project-rowan-cota @@ -135,7 +135,7 @@ \ of the product\n" event: Write the Docs Prague 2018 name: Ivana Devcic - path: conf/prague/2018/videos/it-s-a-feature-documenting-known-issues-and-product-shortcomings-ivana-devcic + path: https://www.youtube.com/watch?v=r-6FycuppXg series: Write the Docs Prague series_slug: prague slug: it-s-a-feature-documenting-known-issues-and-product-shortcomings-ivana-devcic @@ -158,7 +158,7 @@ \ some ways to avoid these pitfalls and bridge the gap with your reader.

    " event: Write the Docs Prague 2018 name: Jim Fisher - path: conf/prague/2018/videos/don-t-say-simply-jim-fisher + path: https://www.youtube.com/watch?v=gsT2BBWBVmM series: Write the Docs Prague series_slug: prague slug: don-t-say-simply-jim-fisher @@ -190,7 +190,7 @@ \ and practical advice.

    " event: Write the Docs Prague 2018 name: Liam Keegan - path: conf/prague/2018/videos/measuring-the-impact-of-your-documentation-liam-keegan + path: https://www.youtube.com/watch?v=48Ga-0_39-o series: Write the Docs Prague series_slug: prague slug: measuring-the-impact-of-your-documentation-liam-keegan @@ -210,7 +210,7 @@ and brings happiness to a diverse customer base.

    event: Write the Docs Prague 2018 name: Predrag Mandic - path: conf/prague/2018/videos/run-your-docs-predrag-mandic + path: https://www.youtube.com/watch?v=oW7rWJ2xNZU series: Write the Docs Prague series_slug: prague slug: run-your-docs-predrag-mandic @@ -234,7 +234,7 @@ \ and spirit.

    " event: Write the Docs Prague 2018 name: Vlad Stirbu - path: conf/prague/2018/videos/what-about-compliance-vlad-stirbu + path: https://www.youtube.com/watch?v=tmFI7haJ7bQ series: Write the Docs Prague series_slug: prague slug: what-about-compliance-vlad-stirbu @@ -257,7 +257,7 @@ \ notes, will be available at https://github.com/tibs/markup-history.

    " event: Write the Docs Prague 2018 name: Tony Ibbs - path: conf/prague/2018/videos/a-brief-history-of-text-markup-languages-tony-ibbs + path: https://www.youtube.com/watch?v=P-7hwjocEpM series: Write the Docs Prague series_slug: prague slug: a-brief-history-of-text-markup-languages-tony-ibbs @@ -299,7 +299,7 @@ ve learned while giving it.

    " event: Write the Docs Prague 2018 name: Abigail Sutherland - path: conf/prague/2018/videos/teaching-geeks-to-fish-tales-of-a-contagious-documentarian-abigail-sutherland + path: https://www.youtube.com/watch?v=3IlcJYKdP1g series: Write the Docs Prague series_slug: prague slug: teaching-geeks-to-fish-tales-of-a-contagious-documentarian-abigail-sutherland @@ -330,7 +330,7 @@ \ helpful insights and lessons learned along the way.

    " event: Write the Docs Prague 2018 name: Sarah Ley-Hamilton - path: conf/prague/2018/videos/so-you-want-to-make-videos-sarah-ley-hamilton + path: https://www.youtube.com/watch?v=PyGJiUIMGpw series: Write the Docs Prague series_slug: prague slug: so-you-want-to-make-videos-sarah-ley-hamilton @@ -359,7 +359,7 @@ \ customer pain points (to manage through customer documentation)\n" event: Write the Docs Prague 2018 name: Gillian von Runte - path: conf/prague/2018/videos/document-what-matters-lean-best-practice-for-process-documentation-gillian-von-runte + path: https://www.youtube.com/watch?v=RpEb8XLH-1A series: Write the Docs Prague series_slug: prague slug: document-what-matters-lean-best-practice-for-process-documentation-gillian-von-runte @@ -384,7 +384,7 @@ \ change...

    " event: Write the Docs Prague 2018 name: Val Grimm - path: conf/prague/2018/videos/choosing-a-tool-and-choosing-your-moment-val-grimm + path: https://www.youtube.com/watch?v=vbbHekptzjw series: Write the Docs Prague series_slug: prague slug: choosing-a-tool-and-choosing-your-moment-val-grimm @@ -417,7 +417,7 @@ \ all of this work without additional full\u2010time documentation help.

    " event: Write the Docs Prague 2018 name: Alexandra White - path: conf/prague/2018/videos/how-to-tear-down-existing-documentation-and-rewrite-docs-that-actually-work-alexandra-white + path: https://www.youtube.com/watch?v=u119GkGSYII series: Write the Docs Prague series_slug: prague slug: how-to-tear-down-existing-documentation-and-rewrite-docs-that-actually-work-alexandra-white diff --git a/docs/_ext/utils.py b/docs/_ext/utils.py index 7219be2517..25274e47b3 100644 --- a/docs/_ext/utils.py +++ b/docs/_ext/utils.py @@ -13,36 +13,6 @@ def slugify(slug): slug = re.sub(r'[^a-z0-9]+', '-', slug).strip('-') slug = re.sub(r'[-]+', '-', slug) return slug - - -def generate_video_slug(session): - """ - Generate a slug for the video of a session, based on title/speakers. - """ - if 'slug' in session: - return session['slug'] - if 'title' not in session: - return u'' - title = session['title'] - for speaker in session.get('speakers', []): - title += '-{}'.format(speaker.get('slug', speaker['name'])) - return slugify(title) - - -def normalize_session(session): - """ - Ensure a dict representing a conference session contains - a correct slug and youtube ID. - """ - youtube_pattern = re.compile(r'https://www.youtube.com/watch\?v=(.+)') - - session['slug'] = generate_video_slug(session) - if 'video' in session and 'youtube.com' in session['video']: - mo = youtube_pattern.match(session['video']) - if mo: - session['youtubeId'] = mo.group(1) - - def load_yaml(path): with io.open(path, encoding='utf-8') as fp: return yaml.safe_load(fp) diff --git a/docs/_ext/videos.py b/docs/_ext/videos.py deleted file mode 100644 index e8ba391c1f..0000000000 --- a/docs/_ext/videos.py +++ /dev/null @@ -1,162 +0,0 @@ -""" -Video archive creator - -Create new videos by adding the following to ``conf.py``:: - - from ._ext.videos import main - - html_context.update(main()) -""" -from __future__ import print_function - -import glob -import re - -from builtins import str -import io -import os -import os.path - -from _ext.utils import generate_video_slug, load_yaml, normalize_session -from docutils.parsers import rst -from sphinxcontrib.datatemplates.directive import DataTemplateYAML - - -def load_conference_data(): - """ - Generate a dict with all data of all conferences including - session details. - """ - # Speakers are the legacy format, >=2020 conferences have a sessions file - speakers_file_pattern = re.compile(r'(\d{4}).(\w+).speakers') - sessions_file_pattern = re.compile(r'(\w+)-(\d{4})-sessions') - result = {} - for f in glob.glob('_data/*.yaml'): - base = os.path.basename(f) - base, _ = os.path.splitext(base) - # Only consider conference data files that are following the common - # naming convention and log everything out as warning. - mo = speakers_file_pattern.match(base) - if mo: - year = int(mo.group(1)) - region = mo.group(2) - if year not in result: - result[year] = {} - if region not in result[year]: - result[year][region] = {} - result[year][region]['speakers'] = load_yaml(f) - for session in result[year][region]['speakers']: - normalize_session(session) - region_display = format_region(region) - session['year'] = year - session['series'] = u'Write the Docs {}'.format(region_display) - session['series_slug'] = region - session['event'] = u'Write the Docs {} {}'.format(region_display, year) - session['path'] = 'conf/{series_slug}/{year}/videos/{slug}'.format(**session) - continue - mo = sessions_file_pattern.match(base) - if mo: - region = mo.group(1) - year = int(mo.group(2)) - if year not in result: - result[year] = {} - if region not in result[year]: - result[year][region] = {} - result[year][region]['speakers'] = load_yaml(f) - for session in result[year][region]['speakers']: - normalize_session(session) - region_display = format_region(region) - session['year'] = year - session['series'] = u'Write the Docs {}'.format(region_display) - session['series_slug'] = region - session['event'] = u'Write the Docs {} {}'.format(region_display, year) - session['path'] = 'conf/{series_slug}/{year}/videos/{slug}'.format(**session) - continue - return result - - -def generate_video_content(session, year, region, session_idx): - data = session.copy() - if 'title' not in session: - return u'' - data['title_marker'] = u'=' * len(data['title']) - data['year'] = year - data['region'] = region - data['session_idx'] = session_idx - - data['data_file'] = f'/_data/{year}.{region}.speakers.yaml' if year < 2020 else f'/_data/{region}-{year}-sessions.yaml' - return u'''{title} -{title_marker} - -.. datatemplate-video:: - :source: {data_file} - :template: videos/video-detail.html - :key: {session_idx} - -'''.format(**data) - - -def generate_video_listing(year, series): - data_file = f'/_data/{year}.{series}.speakers.yaml' if year < 2020 else f'/_data/{series}-{year}-sessions.yaml' - return u'''Videos of Write the Docs {series_title} {year} -============================================================= - -.. toctree:: - :glob: - :hidden: - - * - -.. datatemplate:: - :source: {data_file} - :template: videos/video-listing.html -'''.format(year=year, series=series, series_title=format_region(series), data_file=data_file) - - -def main(): - conference_data = load_conference_data() - - for year, regions in list(conference_data.items()): - for region, data in list(regions.items()): - has_videos = False - for speaker in data['speakers']: - if speaker.get('youtubeId'): - has_videos = True - break - - if not has_videos: - continue - - index_path = os.path.join('videos', region, str(year)) - if not os.path.exists(index_path): - os.makedirs(index_path) - with io.open(os.path.join(index_path, 'index.rst'), 'w+') as fp: - fp.write(generate_video_listing(year, region)) - - for idx, speaker in enumerate(data['speakers']): - if year > 2023: - video_slug = generate_video_slug(speaker) - video_path = os.path.join(index_path, video_slug) - video_content = generate_video_content(speaker, year, region, idx) - with io.open(video_path + '.rst', 'w+') as fp: - fp.write(video_content) - - return { - 'conf_py_root': os.path.dirname(os.path.dirname(os.path.abspath(__file__))), - 'conferences': conference_data, - } - - -class DataTemplateVideo(DataTemplateYAML): - option_spec = dict(DataTemplateYAML.option_spec, **{ - 'key': rst.directives.nonnegative_int, - }) - - def _make_context(self, data, config, env): - context = super()._make_context(data, config, env) - context['key'] = self.options.get('key') - return context - - -def format_region(region): - return region.title() if len(region) > 2 else region.upper() diff --git a/docs/_static_html/conf/na/2015/news/videos-forum-eu-cfp/index.html b/docs/_static_html/conf/na/2015/news/videos-forum-eu-cfp/index.html index 233e6f443b..d52390dfe9 100644 --- a/docs/_static_html/conf/na/2015/news/videos-forum-eu-cfp/index.html +++ b/docs/_static_html/conf/na/2015/news/videos-forum-eu-cfp/index.html @@ -180,7 +180,7 @@

    Meetups

    Videos

    We have videos of every talk from our conference this year. If you missed something, you can always catch it on video.

    -

    Check out previous talks, too. We’ve also recorded every talk at Write the Docs from every year.

    +

    Check out previous talks, too. All of our recordings are on the Write the Docs YouTube channel.

    2016

    diff --git a/docs/about/learning-resources.rst b/docs/about/learning-resources.rst index 61d8870295..01861ce5a0 100644 --- a/docs/about/learning-resources.rst +++ b/docs/about/learning-resources.rst @@ -29,7 +29,7 @@ Our monthly :doc:`/newsletter` aggregates the latest discussions about topics th Videos ~~~~~~ -All the presentation `videos `_ are available on YouTube so that you can catch up on the content even if you can't attend the conferences. +All the presentation videos are available on our `YouTube channel `_ so that you can catch up on the content even if you can't attend the conferences. Podcast ~~~~~~~ diff --git a/docs/blog/2020-community-update.rst b/docs/blog/2020-community-update.rst index e9dbcad517..43e8de86c1 100644 --- a/docs/blog/2020-community-update.rst +++ b/docs/blog/2020-community-update.rst @@ -17,7 +17,7 @@ The talks were just announced for the Prague conference, we'll be publishing mor We also just recently wrapped up our first online Portland conference. We had around 600 people join us to make this another memorable event. -The `videos `_ from the conference are now available online. +The videos from the conference are now available on our `YouTube channel `_. Salary Survey ------------- diff --git a/docs/blog/2021-community-update.rst b/docs/blog/2021-community-update.rst index 3b0dee8da0..a5620a2abd 100644 --- a/docs/blog/2021-community-update.rst +++ b/docs/blog/2021-community-update.rst @@ -18,7 +18,7 @@ The talks were just announced for the Prague conference, and the `Australia & In We also had our second virtual Portland conference in April this year. It was another success with almost 700 people attending from all over the world. -The `videos `_ from the conference are now available online. +The videos from the conference are now available on our `YouTube channel `_. Write the Docs Enhancement Proposals (WEPs) ------------------------------------------- diff --git a/docs/blog/newsletter-april-2018.rst b/docs/blog/newsletter-april-2018.rst index 689136eed7..130671890b 100644 --- a/docs/blog/newsletter-april-2018.rst +++ b/docs/blog/newsletter-april-2018.rst @@ -14,7 +14,7 @@ First, we're coming up on the Portland conference here in just four weeks (!?), Tickets are fully sold out, but if you're itching for a conference fix, now's a great time to look ahead to Prague in September... especially if you'd like to speak! The Prague call for proposals is open until **midnight, Tuesday May 15th**, and you can read more and submit your talk idea `here on our CFP page `_. -We also have a new virtual resource to announce – the `Write the Docs Video Archive `_! +We also have a new virtual resource to announce – the `Write the Docs YouTube channel `_! You can now easily browse all of the videos from every North American and European conference, going back over the last three years. There are hours of excellent talks in there, on almost any docs-topic you can think of. Dive in! diff --git a/docs/blog/newsletter-april-2019.rst b/docs/blog/newsletter-april-2019.rst index 8249f05af9..04c559ec39 100644 --- a/docs/blog/newsletter-april-2019.rst +++ b/docs/blog/newsletter-april-2019.rst @@ -66,7 +66,7 @@ Lots of commenters talked about helping those asking you to understand the situa It's worth checking if the person requesting can help by gathering the information needed. If they agree to do the groundwork, it takes some of the burden of emergency work off you. -Be aware that you likely won't find time to think strategically: you have to make it. One suggestion was to block off time in your calendar for this, even if you can only start small. For an idea of what to do, see `Neal Kaplan's talk on triaging `_. +Be aware that you likely won't find time to think strategically: you have to make it. One suggestion was to block off time in your calendar for this, even if you can only start small. For an idea of what to do, see `Neal Kaplan's talk on triaging `_. And keep taking care of yourself - knowledge work requires a functioning brain! If you're fried, don't be afraid to take the breaks you need. diff --git a/docs/blog/newsletter-august-2019.rst b/docs/blog/newsletter-august-2019.rst index 9d22c6cb35..5167259c8b 100644 --- a/docs/blog/newsletter-august-2019.rst +++ b/docs/blog/newsletter-august-2019.rst @@ -26,7 +26,7 @@ A question about how to improve on tools like `Javadoc `__. For a discussion of the benefits of writers and developers working together, see our editor's talk `Who Writes the Docs? `__ +For more about a successful Javadoc/doxygen project that included writers and developers, check out Jennifer Rondeau's `Symantec case study `__. For a discussion of the benefits of writers and developers working together, see our editor's talk `Who Writes the Docs? `__ ------------------------------- Using writing tests when hiring @@ -58,7 +58,7 @@ Diagrams and technical illustrations were a hot topic this month. Here are some Resources the community mentioned: * `Mike Parkinson's (of BillionDollarGraphics) Graphic Cheat Sheet `__ -* `Alicia Raszkowska's talk "Draw the Docs" `__ +* `Alicia Raszkowska's talk "Draw the Docs" `__ * `The Back of the Napkin by Dan Roam `__ * `Trees, maps, and theorems by Jean-luc Dumont `__ @@ -100,7 +100,7 @@ Analytics, metrics, measuring docs quality -- different names for similar questi - Other potentially useful data includes device type (mobile/desktop/tablet), browser, and language. - Try Google Tag Manager for managing GA tracking -- it lets you start tracking more items without adding extra code to your site. -People were quick to point out that, while GA shows you what data you can collect automatically, you really need to think about what you want to learn about your docs and users, then pick metrics to achieve those goals. Start with the questions, then gather the data! (More in `Sarah Moir's great talk from Portland `__.) +People were quick to point out that, while GA shows you what data you can collect automatically, you really need to think about what you want to learn about your docs and users, then pick metrics to achieve those goals. Start with the questions, then gather the data! (More in `Sarah Moir's great talk from Portland `__.) A particular question about measuring ROI generated its own round of ideas and suggestions: diff --git a/docs/blog/newsletter-december-2024.rst b/docs/blog/newsletter-december-2024.rst index dfcd9ba41a..37103d4550 100644 --- a/docs/blog/newsletter-december-2024.rst +++ b/docs/blog/newsletter-december-2024.rst @@ -61,14 +61,14 @@ Searching and browsing are complementary actions. The method used by any one per **Search-related resources** * `Search platform tips for documentation websites `_ (WTD Newsleter) -* `Making documentation discoverable in search engines `_ (WTD video) +* *Making documentation discoverable in search engines* (available on our `YouTube channel `_) * `Search engine optimization (SEO) for documentation `_ (WTD page) * `Information Foraging `_ (Nielsen Norman Group) **Navigation- and IA-related resources** * Many articles available from `Nielsen Norman Group `__ -* `Building navigation for your doc site: 5 best practices `__ (WTD video) +* *Building navigation for your doc site: 5 best practices* (available on our `YouTube channel `_) * `Complete Beginner’s Guide to Information Architecture `__ (UX Booth) * `How To Make Sense of Any Mess `_ (book by Abby Covert) diff --git a/docs/blog/newsletter-february-2019.rst b/docs/blog/newsletter-february-2019.rst index 705db6ea45..d94d951d8f 100644 --- a/docs/blog/newsletter-february-2019.rst +++ b/docs/blog/newsletter-february-2019.rst @@ -57,8 +57,8 @@ We have so many people who are the only writer in their company that there's a c Some useful resources: -* `Bootstrapping Docs at a Startup `_ - Jesse Seldess, Write the Docs Portland 2017 -* `Where Do I Start: The Art and Practice of Documentation Triage `_ - Neal Kaplan, Write the Docs Portland 2018 +* `Bootstrapping Docs at a Startup `_ - Jesse Seldess, Write the Docs Portland 2017 +* `Where Do I Start: The Art and Practice of Documentation Triage `_ - Neal Kaplan, Write the Docs Portland 2018 * `The Lone Writers Guide `_ - GitHub project. It's a work in progress, and they welcome contributions! -------------------------------------------------- diff --git a/docs/blog/newsletter-february-2021.rst b/docs/blog/newsletter-february-2021.rst index 2074d969a2..742a387321 100644 --- a/docs/blog/newsletter-february-2021.rst +++ b/docs/blog/newsletter-february-2021.rst @@ -24,7 +24,7 @@ A middle-ground approach is using text descriptions of UI elements, like "Click What about a video walkthrough or GIFs? Again, documentarians were split: it's helpful to watch a process through before trying it yourself, but videos and GIFs are inaccessible for people with visual impairments, distracting for people with attention issues, and unusable for people who don't have dependable broadband service. And following video instructions can be frustrating if you have to repeatedly press pause, or feel like the pace of spoken instructions is too slow. -For more on screenshots in documentation, check out Steve Stegelin's `Graphic Content Warning: The Pros, Cons, and Alternatives to Screenshots `_ from Write the Docs Portland 2018 and Swapnil Ogale's `When bad screenshots happen to good writers `_ from WTD EU 2016. +For more on screenshots in documentation, check out Steve Stegelin's *Graphic Content Warning: The Pros, Cons, and Alternatives to Screenshots* and Swapnil Ogale's *When bad screenshots happen to good writers* on our `YouTube channel `_. -------------------------------------- Report from the book club: managing up diff --git a/docs/blog/newsletter-july-2019.rst b/docs/blog/newsletter-july-2019.rst index b2a70ba414..bc7cba7993 100644 --- a/docs/blog/newsletter-july-2019.rst +++ b/docs/blog/newsletter-july-2019.rst @@ -41,8 +41,8 @@ As they're often the first thing people see about a code project, READMEs are pr * `Art of README `_ * `Standard README `_ -* `Write the Readable README `_ (Daniel Beck @ Write the Docs NA 2016), and Daniel's `README checklist `_ -* `Hi, my name is README! `_ (Raphael Pierzina @ Write the Docs EU 2017) +* `Write the Readable README `_ (Daniel Beck @ Write the Docs NA 2016), and Daniel's `README checklist `_ +* `Hi, my name is README! `_ (Raphael Pierzina @ Write the Docs EU 2017) * `Ten Steps to a Better README `_ (Mike Jang @ Ignite OSCON 2015) * `Developer Experience: GitHub READMEs `_ (Cristlano Betta's blog post) * `READMEs and doc-driven development `_ (August 2017 WTD newsletter) diff --git a/docs/blog/newsletter-july-2025.rst b/docs/blog/newsletter-july-2025.rst index df0599faad..d9a6690dd6 100644 --- a/docs/blog/newsletter-july-2025.rst +++ b/docs/blog/newsletter-july-2025.rst @@ -37,7 +37,7 @@ The next time you're considering auditing your documentation, consider these ide Start by clarifying your goals. You might only want to map your content, or you might want to improve it. You might know specific issues you need to fix, or you might be trying to uncover them. Think about how ambitious your audit should be and how much time you can dedicate. -Consider who else to include in the audit: a technical writer who is familiar with the style guide, subject matter experts, someone who represents users' interests? If you need to improve docs that are new to you, check out the talk `Where do I start? The art and practice of documentation triage `_. A more general resource that goes well beyond documentation is `Content Audits and Inventories: A Handbook for Content Analysis `_. +Consider who else to include in the audit: a technical writer who is familiar with the style guide, subject matter experts, someone who represents users' interests? If you need to improve docs that are new to you, check out the talk `Where do I start? The art and practice of documentation triage `_. A more general resource that goes well beyond documentation is `Content Audits and Inventories: A Handbook for Content Analysis `_. If it fits your goals, establish a checklist that lists the quality standards and required features to evaluate each page of documentation against, such as grammar, formatting, and accuracy. Select a doc that's already in great shape to represent the ideal and give you a point of comparison. A previous newsletter item, `Measuring Docs Quality `_, may help you shape the checklist. diff --git a/docs/blog/newsletter-june-2018.rst b/docs/blog/newsletter-june-2018.rst index 23f40ec5cc..8dad21cfd8 100644 --- a/docs/blog/newsletter-june-2018.rst +++ b/docs/blog/newsletter-june-2018.rst @@ -67,7 +67,7 @@ Short advice for writing error messages --------------------------------------- This month, the hivemind fielded a request for advice about writing good error messages. Attached to the request, though, was a familiar (and vital) caveat: They needed short, easy-to-digest pointers, rather than longer, meatier reads, in an effort to boost the odds that their developer teams would actually find the time to read what they shared. -One of the top suggestions was Kate Voss's `Error Messages talk at WTD Portland 2017 `_ We'll admit that a 15-minute video doesn't fit the "short" parameter...but Kate's own distillation of her talk brings it down to three concise rules: Humble, Helpful, and Human. +One of the top suggestions was Kate Voss's *Error Messages* talk from WTD Portland 2017 (available on our `YouTube channel `_). We'll admit that a 15-minute video doesn't fit the "short" parameter...but Kate's own distillation of her talk brings it down to three concise rules: Humble, Helpful, and Human. * **Humble**: apologize and acknowledge the error * **Helpful**: make sure the error message tells users what to do next diff --git a/docs/blog/newsletter-june-2019.rst b/docs/blog/newsletter-june-2019.rst index a2de9ae0f0..c1d70cffbe 100644 --- a/docs/blog/newsletter-june-2019.rst +++ b/docs/blog/newsletter-june-2019.rst @@ -20,7 +20,7 @@ Many people have been keeping the Portland conference spirit alive by posting wr - `A list of resources put together by a generous community member `__ (taken from Slack links and posts). Includes links to blog posts, writeups of API docs and inclusivity unconference sessions, resources for drawing docs, and much more. - `A twitter thread with a writeup of the unconference session on measuring success `__. - `The Writing Day project on learning Git to contribute to the Write the Docs website `__. -- And of course, `all the talk videos `__ are now live! +- And of course, `all the talk videos `__ are now live! --------------------------------- Facilitating top-notch doc review @@ -74,15 +74,15 @@ Order from chaos, or, a conversation about docs cleanup Over the years, how to organize your docs been a really popular topic at Write the Docs conferences. One notable piece of advice was to seek out and make public the often-hidden or kept-private stashes of information that individuals in a company invariably gather. If it's a problem you're interested in, there's an embarrassment of riches for you in the video archives: -- `What can brownfield do for you? `__ - Mo Nishiyama, Portland 2015 -- `User-story driven docs `__ - Joao Fernandes, Portland 2015 -- `MacGyvering your docs `__ - Paul Roeland, Prague 2015 -- `Bootstrapping docs at a startup `__ - Jesse Seldess, Portland 2017 +- `What can brownfield do for you? `__ - Mo Nishiyama, Portland 2015 +- `User-story driven docs `__ - Joao Fernandes, Portland 2015 +- `MacGyvering your docs `__ - Paul Roeland, Prague 2015 +- `Bootstrapping docs at a startup `__ - Jesse Seldess, Portland 2017 - `Backseat content strategy `__ - Laura Bailey, Australia 2018 -- `Where do I start? The art and practice of documentation triage `__ - Neil Kaplan, Portland 2018 -- `How to tear down existing documentation and rewrite docs that actually work `__ - Alexandra White, Prague 2018 +- `Where do I start? The art and practice of documentation triage `__ - Neil Kaplan, Portland 2018 +- `How to tear down existing documentation and rewrite docs that actually work `__ - Alexandra White, Prague 2018 - Tackling technical debt in the docs - Louise Fahey, Prague 2018 -- `A year in the life of the better docs project `__ - Rowan Cota, Prague 2018 +- `A year in the life of the better docs project `__ - Rowan Cota, Prague 2018 -------------------- DITA vs docs-as-code diff --git a/docs/blog/newsletter-june-2020.rst b/docs/blog/newsletter-june-2020.rst index 12f24a2855..9444dde813 100644 --- a/docs/blog/newsletter-june-2020.rst +++ b/docs/blog/newsletter-june-2020.rst @@ -31,7 +31,7 @@ First, create a docs page that lists only the product links to docs topics. Then Types of docs and how to use them --------------------------------- -Back in 2017, Daniele Procida gave an often cited talk, `The four kinds of documentation, and why you need to understand what they are `__, written up into `this article `__. Our community spent some time discussing the details of how to apply Danielel's type distinctions, with some help from Daniele himself. As a refresher, the four types are: +Back in 2017, Daniele Procida gave an often cited talk, `The four kinds of documentation, and why you need to understand what they are `__, written up into `this article `__. Our community spent some time discussing the details of how to apply Danielel's type distinctions, with some help from Daniele himself. As a refresher, the four types are: * Tutorials, or learning-oriented docs * How-to guides, or problem-solving docs diff --git a/docs/blog/newsletter-may-2019.rst b/docs/blog/newsletter-may-2019.rst index bb30ffe631..72598a2947 100644 --- a/docs/blog/newsletter-may-2019.rst +++ b/docs/blog/newsletter-may-2019.rst @@ -33,9 +33,9 @@ The two biggest challenges were prioritizing feedback-based improvements without And of course, some WTD talks have covered user feedback too: -* `CSAT - what’s that? `_ -* `Feedback handling, community wrangling, panhandling `_ -* `You have already succeeded 2.0 `_ +* `CSAT - what’s that? `_ +* `Feedback handling, community wrangling, panhandling `_ +* `You have already succeeded 2.0 `_ ------------------------------------ Tips and tricks for producing videos diff --git a/docs/blog/newsletter-september-2021.rst b/docs/blog/newsletter-september-2021.rst index a3b497f0f4..7e0e799f1d 100644 --- a/docs/blog/newsletter-september-2021.rst +++ b/docs/blog/newsletter-september-2021.rst @@ -19,7 +19,7 @@ Avoiding the dreaded "wall of text" The "wall of text" is a familiar conundrum for many documentarians, especially when a topic requires in-depth explanation. As writers and as readers ourselves, we want docs that provide sufficient detail and are skimmable at the same time. Here are some strategies that go beyond surface-level fixes to also add helpful context and support a better user experience: - Add thoughtful headings and subheadings to provide content signposts and help readers find information they might otherwise miss in a long span of text. Meaningful headings do more than just break up the text - they provide a mental picture of everything on the page and allow readers to focus on the pieces they really need to understand. -- Use progressive disclosure, like linking to secondary pages for details or using expandable panels, to keep the entire text available without overwhelming readers at first glance. Learn more about progressive disclosure from this 2017 Write the Docs Portland talk, `Building navigation for your doc site: 5 best practices `__, by Tom Johnson. +- Use progressive disclosure, like linking to secondary pages for details or using expandable panels, to keep the entire text available without overwhelming readers at first glance. Learn more about progressive disclosure from this 2017 Write the Docs Portland talk, `Building navigation for your doc site: 5 best practices `__, by Tom Johnson. - Rewrite long paragraphs to use lists. Condense the most critical points to eye-catching items in a list and make the text more skimmable. Write instructions in individually numbered steps. - Look for opportunities to use formatting to add meaning to the text. Use special icons or different background shading to delineate notes and warnings. Put code snippets, quotations, and math equations in their own indented blocks. Use bold font weight to make keywords stand out. Left-justify the first paragraph for each topic and block-indent subsequent paragraphs on the same topic. diff --git a/docs/blog/newsletter-september-2023.rst b/docs/blog/newsletter-september-2023.rst index ec8930ebd3..b8e73864ba 100644 --- a/docs/blog/newsletter-september-2023.rst +++ b/docs/blog/newsletter-september-2023.rst @@ -31,7 +31,7 @@ Look for opportunities to encourage a sense of ownership among those who contrib Other recommendations for further information: -- `Any friend of the docs is a friend of mine: Cultivating a community of documentation advocates `__ from Write the Docs Portland, 2019 +- `Any friend of the docs is a friend of mine: Cultivating a community of documentation advocates `__ from Write the Docs Portland, 2019 - `2022 State of DevOps Report data deep dive: Documentation is like sunshine `__ - `Why it’s worth it to invest in internal docs `__ diff --git a/docs/blog/write-the-docs-2016-year-in-review.rst b/docs/blog/write-the-docs-2016-year-in-review.rst index 0c9b2638c0..696a31c9b5 100644 --- a/docs/blog/write-the-docs-2016-year-in-review.rst +++ b/docs/blog/write-the-docs-2016-year-in-review.rst @@ -21,7 +21,7 @@ They are the time each year where hundreds of wonderful folks gather and have a while learning so much from each other. Proving each year that work can be both fun and informative is one of my greatest pleasures. -We continue to publish `videos `_ freely to the public. +We continue to publish `videos on YouTube `_ freely to the public. This is done so that the information can be most widely shared, and help people who may not be able to attend the events. Write the Docs always strives to be as inclusive as possible, diff --git a/docs/blog/write-the-docs-2017-stats.rst b/docs/blog/write-the-docs-2017-stats.rst index 987ad394e8..fbbf581030 100644 --- a/docs/blog/write-the-docs-2017-stats.rst +++ b/docs/blog/write-the-docs-2017-stats.rst @@ -27,7 +27,7 @@ We have sold out both the Portland & Prague :doc:`conferences ` the We've intentionally kept them smaller to maintain the intimate feel of the events, but might grow them slowly over time in order to accommodate more people. -We continue to publish `videos `_ freely to the public. +We continue to publish `videos on YouTube `_ freely to the public. Doing this is more inclusive to people who cannot attend the conferences, promotes learning, and is part of our :doc:`commitment to openness `. Slack Network diff --git a/docs/conf.py b/docs/conf.py index 6063e68101..3a798352c1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -66,13 +66,13 @@ def _load_data(self, env, data_source, encoding): from _ext.filters import add_jinja_filters_to_app from _ext.meetups import MeetupListing from _ext.atom_absolute import rewrite_atom_feed -from _ext import videos exclude_patterns = [ '_build', 'include', #'_data', 'node_modules', + 'videos/**', 'videos/prague/2018/tackling-technical-debt-in-the-docs-louise-fahey.rst', ] @@ -91,16 +91,8 @@ def _load_data(self, env, data_source, encoding): else: print('Private CFP environment variables not set, not building CFP email templates.') -# Only build the videos on production, to speed up dev on_rtd = str(os.environ.get('READTHEDOCS')).lower() == 'true' -build_videos = str(os.environ.get('BUILD_VIDEOS')).lower() == 'true' -if not on_rtd and not build_videos: - print('EXCLUDING VIDEO PATHS. Video links will not work.') - exclude_patterns.append('videos') - REWRITE_FEED = False -else: - print('BUILDING VIDEOS. All video links should work.') - REWRITE_FEED = True +REWRITE_FEED = on_rtd extensions = [ 'ablog', @@ -233,10 +225,6 @@ def _load_data(self, env, data_source, encoding): 'announcement_message': announcement_message, } -if build_videos: - - html_context.update(videos.main()) - notfound_no_urls_prefix = True @@ -261,11 +249,10 @@ def add_metadata(app, pagename, templatename, context, doctree): # Render HTML templates with proper HTML context app.connect('html-page-context', override_template_load_context) - if on_rtd or build_videos or REWRITE_FEED: + if on_rtd or REWRITE_FEED: app.connect('build-finished', rewrite_atom_feed) app.add_directive('meetup-listing', MeetupListing) - app.add_directive('datatemplate-video', videos.DataTemplateVideo) app.add_css_file('css/global-customizations.css') app.add_css_file('css/survey.css') diff --git a/docs/conf/australia/2021/welcome-wagon.rst b/docs/conf/australia/2021/welcome-wagon.rst index 36d8ec9618..c2a338def5 100644 --- a/docs/conf/australia/2021/welcome-wagon.rst +++ b/docs/conf/australia/2021/welcome-wagon.rst @@ -76,7 +76,7 @@ To attend the moderated Q&A after each talk, go to **Sessions** and select the * Watching talks after the conference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Don't worry if you miss something in a talk! Stage talks and Q&A sessions are recorded. Videos will be published in the `Write the Docs Video Archive `__ shortly after the conference (typically about a week after the conference ends). To be notified when videos are published, `sign up for our newsletter `__ or `subscribe to our YouTube channel `__. +Don't worry if you miss something in a talk! Stage talks and Q&A sessions are recorded. Videos will be published on the `Write the Docs YouTube channel `__ shortly after the conference (typically about a week after the conference ends). To be notified when videos are published, `sign up for our newsletter `__ or `subscribe to our YouTube channel `__. Other sessions (such as Unconference, Hallway, and Writing Day sessions) are not recorded. diff --git a/docs/conf/australia/2022/welcome-wagon.rst b/docs/conf/australia/2022/welcome-wagon.rst index ba78ef41dc..e05d8891b2 100644 --- a/docs/conf/australia/2022/welcome-wagon.rst +++ b/docs/conf/australia/2022/welcome-wagon.rst @@ -76,7 +76,7 @@ To attend the moderated Q&A after each talk, go to **Sessions** and select the * Watching talks after the conference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Don't worry if you miss something in a talk! Stage talks and Q&A sessions are recorded. Videos will be published in the `Write the Docs Video Archive `__ shortly after the conference (typically about a week after the conference ends). To be notified when videos are published, `sign up for our newsletter `__ or `subscribe to our YouTube channel `__. +Don't worry if you miss something in a talk! Stage talks and Q&A sessions are recorded. Videos will be published on the `Write the Docs YouTube channel `__ shortly after the conference (typically about a week after the conference ends). To be notified when videos are published, `sign up for our newsletter `__ or `subscribe to our YouTube channel `__. Other sessions (such as Unconference, Hallway, and Writing Day sessions) are not recorded. diff --git a/docs/conf/portland/2018/news/thanks-recap.rst b/docs/conf/portland/2018/news/thanks-recap.rst index ccdb19d1c6..e5ea77df96 100644 --- a/docs/conf/portland/2018/news/thanks-recap.rst +++ b/docs/conf/portland/2018/news/thanks-recap.rst @@ -40,9 +40,8 @@ see our awesome community gather out in the physical world. Videos and photos and write-ups =============================== -Videos of all the talks are now available `in our video -archive `__. Thanks -to `Backpedal `__ for doing such a great job with these. +Videos of all the talks are now available on our `YouTube channel `__. Thanks +to `Backpedal `__ for doing such a great job with these. If you gave a lightning talk, we're working to get them on our site, but you can see them on `YouTube `__ diff --git a/docs/conf/portland/2019/news/thanks-recap.rst b/docs/conf/portland/2019/news/thanks-recap.rst index c78ba74b3b..e3007cea0c 100644 --- a/docs/conf/portland/2019/news/thanks-recap.rst +++ b/docs/conf/portland/2019/news/thanks-recap.rst @@ -33,9 +33,8 @@ and we had a great time. Videos and photos ================= -Videos of all the talks are now available `in our video -archive `__. Thanks -to `Backpedal `__ for doing such a great job with these. +Videos of all the talks are now available on our `YouTube channel `__. Thanks +to `Backpedal `__ for doing such a great job with these. If you gave a lightning talk, we're working to get them on our site, but you can see them on `YouTube `__ diff --git a/docs/conf/prague/2018/news/thanks-recap.rst b/docs/conf/prague/2018/news/thanks-recap.rst index 32a90b68eb..8b08f9df26 100644 --- a/docs/conf/prague/2018/news/thanks-recap.rst +++ b/docs/conf/prague/2018/news/thanks-recap.rst @@ -28,7 +28,7 @@ Overall, we were so excited to see another conference come together and see our Videos and photos ================= -Videos of all the talks are now available `in our video archive `__. +Videos of all the talks are now available on our `YouTube channel `__. Thanks to `Here to Record `__ for doing such a great job with these. If you gave a lightning talk, we're working to get them on our site, but in the meantime you can see them on `YouTube `__ for now. (You can also subscribe to our `YouTube channel `_ diff --git a/docs/conf/prague/2020/welcome-wagon.rst b/docs/conf/prague/2020/welcome-wagon.rst index 6bcd5e36ef..2a90461aab 100644 --- a/docs/conf/prague/2020/welcome-wagon.rst +++ b/docs/conf/prague/2020/welcome-wagon.rst @@ -76,7 +76,7 @@ To attend the moderated Q&A after each talk, go to **Sessions** and select the * Watching talks after the conference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Don't worry if you miss something in a talk! Stage talks and Q&A sessions are recorded. Videos will be published in the `Write the Docs Video Archive `__ shortly after the conference (typically about a week after the conference ends). To be notified when videos are published, `sign up for our newsletter `__ or `subscribe to our YouTube channel `__. +Don't worry if you miss something in a talk! Stage talks and Q&A sessions are recorded. Videos will be published on the `Write the Docs YouTube channel `__ shortly after the conference (typically about a week after the conference ends). To be notified when videos are published, `sign up for our newsletter `__ or `subscribe to our YouTube channel `__. Other sessions (such as Unconference, Hallway, and Writing Day sessions) are not recorded. diff --git a/docs/guide/writing/accessibility.md b/docs/guide/writing/accessibility.md index 0ff3cbfd62..4a440d67b7 100644 --- a/docs/guide/writing/accessibility.md +++ b/docs/guide/writing/accessibility.md @@ -37,6 +37,6 @@ And for general writing style, see [style guides](https://www.writethedocs.org/g ## Relevant talks from Write the Docs: -- [Moving beyond empathy: a11y in documentation](https://www.writethedocs.org/videos/portland/2020/moving-beyond-empathy-a11y-in-documentation-alexandra-white/) -- [A11y-Friendly Documentation](https://www.writethedocs.org/videos/prague/2018/a11y-friendly-documentation-carolyn-stransky/) at Write the Docs Prague 2018 -- [Inclusive Tech Docs - TechComm Meets Accessibility](http://www.writethedocs.org/videos/eu/2015/inclusive-tech-docs-techcomm-meets-accessibility-rmatic/) at Write the Docs EU 2015 +- *Moving beyond empathy: a11y in documentation* (available on our `YouTube channel `_) +- *A11y-Friendly Documentation* from Write the Docs Prague 2018 (available on our `YouTube channel `_) +- *Inclusive Tech Docs - TechComm Meets Accessibility* from Write the Docs EU 2015 (available on our `YouTube channel `_) diff --git a/docs/guide/writing/reducing-bias.md b/docs/guide/writing/reducing-bias.md index 6298b2dc8a..19ea7730f0 100644 --- a/docs/guide/writing/reducing-bias.md +++ b/docs/guide/writing/reducing-bias.md @@ -31,7 +31,7 @@ Paid resources: Relevant talks from Write the Docs: -- [What They Don’t Tell You About Creating New Style Guides](https://www.writethedocs.org/videos/portland/2018/what-they-don-t-tell-you-about-creating-new-style-guides-thursday-bram/) +- *What They Don’t Tell You About Creating New Style Guides* (available on our `YouTube channel `_) ## Providing inclusive example names diff --git a/docs/guide/writing/style-guides.md b/docs/guide/writing/style-guides.md index b494d75d61..d5b467a5b7 100644 --- a/docs/guide/writing/style-guides.md +++ b/docs/guide/writing/style-guides.md @@ -97,7 +97,7 @@ A command-line interface (CLI) processes commands to a computer program in the f Relevant talk from Write the Docs: -- [How I learned to stop worrying and love the CLI](https://www.writethedocs.org/videos/portland/2019/how-i-learned-to-stop-worrying-and-love-the-command-line-mike-jang/) at WTD Portland 2019 +- *How I learned to stop worrying and love the CLI* from WTD Portland 2019 (available on our `YouTube channel `_) ### API documentation @@ -211,7 +211,7 @@ What to avoid: - [App Release Notes Are Getting Stupid -- TechCrunch](https://techcrunch.com/2015/09/04/app-release-notes-are-getting-stupid/) - [Release Notes: 13 Mistakes to Avoid When Writing Bugs and Enhancements -- klariti.com](https://www.klariti.com/technical-writing/2015/05/08/release-notes-mistakes-to-avoid/) Related talks: -- [Learning to love release notes](http://www.writethedocs.org/videos/prague/2018/learning-to-love-release-notes-anne-edwards/) at Write the Docs Prague 2018 +- *Learning to love release notes* from Write the Docs Prague 2018 (available on our `YouTube channel `_) - [Rethinking Release Notes](https://www.youtube.com/watch?v=SWduFnDPjYg) at Write the Docs Australia 2019 diff --git a/docs/include/conf/virtual/welcome-wagon.rst b/docs/include/conf/virtual/welcome-wagon.rst index 0f6fa52b69..a1fabc5465 100644 --- a/docs/include/conf/virtual/welcome-wagon.rst +++ b/docs/include/conf/virtual/welcome-wagon.rst @@ -98,7 +98,7 @@ Watching talks after the conference Don't worry if you miss something in a talk! Stage talks, Q&A sessions, and lightning talks are recorded. -Videos will be published in the `Write the Docs Video Archive `__ shortly after the conference +Videos will be published on the `Write the Docs YouTube channel `__ shortly after the conference (typically about a week after the conference ends). To be notified when videos are published, `sign up for our newsletter `__ or `subscribe to our YouTube channel `__. @@ -350,7 +350,7 @@ Are the talks recorded? ~~~~~~~~~~~~~~~~~~~~~~~ - Stage talks and Q&A sessions are recorded. - Videos will be published in the `Write the Docs Video Archive `__ shortly after the conference + Videos will be published on the `Write the Docs YouTube channel `__ shortly after the conference (typically about a week after the conference ends). - Other sessions (such as Unconference, Hallway, and Writing Day sessions) are not recorded. diff --git a/docs/index.rst b/docs/index.rst index f8932df9b4..f405971fb2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -52,8 +52,9 @@ Work with other documentarians. Learn from our resources ------------------------ -We have an ever-increasing set of talk videos, articles, links, and resources: +We have an ever-increasing set of articles, links, and resources. Watch our talks on YouTube: +* Watch past conference talks on our `YouTube channel `_ * Subscribe to our :doc:`newsletter and conference ` mailing lists * Browse our :doc:`topic index ` * Read the latest in our :doc:`blog ` diff --git a/docs/organizer-guide/meetups/starting.rst b/docs/organizer-guide/meetups/starting.rst index c364e08d19..b3319ca7c3 100644 --- a/docs/organizer-guide/meetups/starting.rst +++ b/docs/organizer-guide/meetups/starting.rst @@ -197,8 +197,8 @@ The following are examples of topics that have worked well for other meetups: If You Can't Find a Local Speaker ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you can't find a local speaker, consider screening a popular talk from one of the -`Write the Docs conferences `_ and inviting the conference presenter to call in for +If you can't find a local speaker, consider screening a popular talk from the +`Write the Docs YouTube channel `_ and inviting the conference presenter to call in for a live Q & A session. Both the Boulder and Austin meetups have done well with this format. * `So you need to document an API `_ diff --git a/docs/organizer-guide/meetups/sustainable-meetups.rst b/docs/organizer-guide/meetups/sustainable-meetups.rst index e383083ee9..88f150c04f 100644 --- a/docs/organizer-guide/meetups/sustainable-meetups.rst +++ b/docs/organizer-guide/meetups/sustainable-meetups.rst @@ -11,7 +11,7 @@ Minimal Viable Meetup checklist * Host a maximum of ten meetups per year. You can skip August and December, since most people are on vacation at that time, or taking a break from their usual activities. * Regular meetups help people plan their commitments. Host your meetup at the same time every month – eg the first Wednesday, or another specific date. * Try to host your meetup in a regular event space to minimize the need to spend time finding new spaces. -* If you can’t find a local speaker for each meetup, consider screening a popular talk from one of our past `Write the Docs conferences `_ and inviting the conference presenter to call in for a live Q & A session. +* If you can’t find a local speaker for each meetup, consider screening a popular talk from our `Write the Docs YouTube channel `_ and inviting the conference presenter to call in for a live Q & A session. * Alternatively, consider hosting a regular informal ‘docs and drinks’ to keep the momentum going with your attendees – these can involve either alcohol or coffee. * Bring in at least two main organizers for your meetup (including yourself). This helps shoulder the burden of organizing and stops you burning out. * Check your scheduling won’t clash with an overlapping meetup that might attract away your attendees. diff --git a/docs/topics.rst b/docs/topics.rst index 23a945399d..03e72d1d31 100644 --- a/docs/topics.rst +++ b/docs/topics.rst @@ -16,11 +16,11 @@ Writing words ------------- - |:newspaper:| `Getting past tech writer's block `__ -- |:movie_camera:| `Don't Say Simply `__ -- |:movie_camera:| `Aw Snap! The Docs, They Are A-Changin’ (with apologies to Bob Dylan) `__ -- |:movie_camera:| `Information micro-architecture: grammar, syntax, and cognitive rhetoric `__ -- |:movie_camera:| `Writing as a non-native speaker `__ -- |:movie_camera:| `Writing So Your Words Are Read `__ +- |:movie_camera:| `Don't Say Simply `__ +- |:movie_camera:| `Aw Snap! The Docs, They Are A-Changin’ (with apologies to Bob Dylan) `__ +- |:movie_camera:| `Information micro-architecture: grammar, syntax, and cognitive rhetoric `__ +- |:movie_camera:| `Writing as a non-native speaker `__ +- |:movie_camera:| `Writing So Your Words Are Read `__ - |:movie_camera:| `Tone in Documentation `__ Grammar @@ -34,8 +34,8 @@ Naming and terminology - |:newspaper:| `Capitalizing Feature Names `__ - |:newspaper:| `Common words and how to identify them `__ -- |:movie_camera:| `Even Naming This Talk Is Hard `__ -- |:movie_camera:| `Whatchamacallit: Controlled Vocabularies for Technical Writers `__ +- |:movie_camera:| `Even Naming This Talk Is Hard `__ +- |:movie_camera:| `Whatchamacallit: Controlled Vocabularies for Technical Writers `__ - Specific writing questions @@ -71,14 +71,14 @@ Editing Code samples ~~~~~~~~~~~~ -- |:movie_camera:| `Creating Quality Sample Code `__ -- |:movie_camera:| `Need Examples? Write Your Own! `__ +- |:movie_camera:| `Creating Quality Sample Code `__ +- |:movie_camera:| `Need Examples? Write Your Own! `__ - |:newspaper:| `Evolving developer docs, code samples `__ - |:newspaper:| `Command prompts in code samples `__ -- |:movie_camera:| `Making Your Code Examples Shine `__ +- |:movie_camera:| `Making Your Code Examples Shine `__ - |:newspaper:| `Storing and testing code snippets `__ - |:newspaper:| `Replaceable content in code snippets `__ -- |:movie_camera:| `Visual Documentation Language `__ +- |:movie_camera:| `Visual Documentation Language `__ Formatting ~~~~~~~~~~ @@ -97,11 +97,11 @@ Screenshots - |:newspaper:| `Automating screenshot capture or translation `__ - |:newspaper:| `When to create screenshots `__ - |:newspaper:| `Tips for creating quality screenshots `__ -- |:movie_camera:| `Graphic Content Warning: The Pros, Cons, and Alternatives to Screenshots `__ +- |:movie_camera:| `Graphic Content Warning: The Pros, Cons, and Alternatives to Screenshots `__ - |:newspaper:| `Automated screenshot-taking `__ - |:newspaper:| `Formatting and updating images and screenshots `__ - |:newspaper:| `Cropping screenshots `__ -- |:movie_camera:| `When bad screenshots happen to good writers `__ +- |:movie_camera:| `When bad screenshots happen to good writers `__ Other media ~~~~~~~~~~~ @@ -112,15 +112,15 @@ Including videos and diagrams. - |:newspaper:| `Inclusiveness in diagrams `__ - |:newspaper:| `Is written content outdated - and is it time for video? `__ - |:newspaper:| `Command prompts in docs `__ -- |:movie_camera:| `Set your data free with model-based architecture diagramming `__ +- |:movie_camera:| `Set your data free with model-based architecture diagramming `__ - |:newspaper:| `Behind the scenes with fonts, emojis, and Unicode `__ - |:newspaper:| `Advice for creating technical illustrations `__ - |:newspaper:| `Tips and tricks for producing video `__ -- |:movie_camera:| `Draw the Docs `__ -- |:movie_camera:| `So you want to make videos? `__ -- |:movie_camera:| `Documentation beyond words `__ -- |:movie_camera:| `Screencasting 101 `__ -- |:movie_camera:| `How to Write an Email `__ +- |:movie_camera:| `Draw the Docs `__ +- |:movie_camera:| `So you want to make videos? `__ +- |:movie_camera:| `Documentation beyond words `__ +- |:movie_camera:| `Screencasting 101 `__ +- |:movie_camera:| `How to Write an Email `__ Writing topics -------------- @@ -135,17 +135,17 @@ Writing topics - |:newspaper:| `Types of docs and how to use them `__ - |:newspaper:| `Choosing the right learning level for a topic `__ - |:newspaper:| `Page length and user preference `__ -- |:movie_camera:| `Checklist the Docs `__ -- |:movie_camera:| `How to Write Documentation for People that Don't Read `__ +- |:movie_camera:| `Checklist the Docs `__ +- |:movie_camera:| `How to Write Documentation for People that Don't Read `__ - |:movie_camera:| `Engage or Die: Four Techniques for Writing Indispensable Docs `__ Task-based writing ~~~~~~~~~~~~~~~~~~ - |:newspaper:| `Task-Based Writing `__ -- |:movie_camera:| `Start with the tasks, not the endpoints `__ -- |:movie_camera:| `Let’s Tell a Story: Scenario-Based Documentation `__ -- |:movie_camera:| `User-Story Driven Docs `__ +- |:movie_camera:| `Start with the tasks, not the endpoints `__ +- |:movie_camera:| `Let’s Tell a Story: Scenario-Based Documentation `__ +- |:movie_camera:| `User-Story Driven Docs `__ API docs ~~~~~~~~ @@ -153,30 +153,30 @@ API docs - |:newspaper:| `Improving your API documentation skills `__ - |:newspaper:| `Should APIs be documented with code? `__ - |:newspaper:| `API design with docs in mind `__ -- |:movie_camera:| `Shuffle ball change: Sashay your way to clearer API documentation `__ -- |:movie_camera:| `Write the API docs before the API exists `__ +- |:movie_camera:| `Shuffle ball change: Sashay your way to clearer API documentation `__ +- |:movie_camera:| `Write the API docs before the API exists `__ - |:newspaper:| `Documenting APIs with "interesting" design choices `__ - |:newspaper:| `When does one API stop and another begin? `__ - |:newspaper:| `API reference docs layout `__ - |:newspaper:| `What do we mean by "API" `__ - |:newspaper:| `Get started with API docs `__ -- |:movie_camera:| `So You Need to Document an API? `__ +- |:movie_camera:| `So You Need to Document an API? `__ READMEs ~~~~~~~ - |:newspaper:| `READMEs on READMEs (and other README-related resources) `__ -- |:movie_camera:| `Hi, my name is README `__ +- |:movie_camera:| `Hi, my name is README `__ - |:newspaper:| `READMEs and doc-driven development `__ -- |:movie_camera:| `Write the Readable README `__ +- |:movie_camera:| `Write the Readable README `__ - |:movie_camera:| `README Driven Development `__ In-app documentation ~~~~~~~~~~~~~~~~~~~~~~ -- |:movie_camera:| `Improve Customer Adoption with UI Help `__ -- |:movie_camera:| `Bake a Little Documentation Love into Your Product `__ -- |:movie_camera:| `Tutorials, Tooltips, and Popups…oh MY! How to ease yourself and your users into in-app messaging. `__ +- |:movie_camera:| `Improve Customer Adoption with UI Help `__ +- |:movie_camera:| `Bake a Little Documentation Love into Your Product `__ +- |:movie_camera:| `Tutorials, Tooltips, and Popups…oh MY! How to ease yourself and your users into in-app messaging. `__ Release notes ~~~~~~~~~~~~~~ @@ -184,7 +184,7 @@ Release notes - |:newspaper:| `Making release notes work: Tips for Documentarians `__ - |:newspaper:| `Changelogs for Docs `__ - |:newspaper:| `Do we tell users what’s new in the docs? `__ -- |:movie_camera:| `Learning to love release notes `__ +- |:movie_camera:| `Learning to love release notes `__ Other specific doc types ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -196,92 +196,92 @@ Including how-tos, reference docs, tutorials, and books. - |:newspaper:| `Documenting YAML Files `__ - |:newspaper:| `Code samples: Comments and placeholder text `__ - |:newspaper:| `Templates for concept documentation `__ -- |:movie_camera:| `How to write a book for (and with) an open source community `__ -- |:movie_camera:| `So you need to give bad news to users… `__ -- |:movie_camera:| `Writing a perfect technical tutorial `__ +- |:movie_camera:| `How to write a book for (and with) an open source community `__ +- |:movie_camera:| `So you need to give bad news to users… `__ +- |:movie_camera:| `Writing a perfect technical tutorial `__ - |:newspaper:| `To answer, or not to answer: FAQs `__ -- |:movie_camera:| `Emulating the Teacher’s Approving Nod in Teaching Material `__ -- |:movie_camera:| `How (and why) to make awesome video tutorials `__ -- |:movie_camera:| `Microcontent: Designing & Developing Reusable Content `__ -- |:movie_camera:| `Writing Backwards: Documenting the End-of-Life of a Product `__ -- |:movie_camera:| `Why SDK Docs Matter — And What I’m Doing About It! `__ -- |:movie_camera:| `The Power of Empathy in Support Documentation: A 5-Step Guide `__ -- |:movie_camera:| `101 to 404s: How to write great error messages `__ -- |:movie_camera:| `SDK Reference Manuals: A flow-based approach `__ -- |:movie_camera:| `"It's a Feature" - Documenting Known Issues and Product Shortcomings `__ -- |:movie_camera:| `Writing the Next Great Tech Book `__ +- |:movie_camera:| `Emulating the Teacher’s Approving Nod in Teaching Material `__ +- |:movie_camera:| `How (and why) to make awesome video tutorials `__ +- |:movie_camera:| `Microcontent: Designing & Developing Reusable Content `__ +- |:movie_camera:| `Writing Backwards: Documenting the End-of-Life of a Product `__ +- |:movie_camera:| `Why SDK Docs Matter — And What I’m Doing About It! `__ +- |:movie_camera:| `The Power of Empathy in Support Documentation: A 5-Step Guide `__ +- |:movie_camera:| `101 to 404s: How to write great error messages `__ +- |:movie_camera:| `SDK Reference Manuals: A flow-based approach `__ +- |:movie_camera:| `"It's a Feature" - Documenting Known Issues and Product Shortcomings `__ +- |:movie_camera:| `Writing the Next Great Tech Book `__ - |:newspaper:| `Code comments and other musings on developer docs `__ -- |:movie_camera:| `The Facts About FAQs `__ -- |:movie_camera:| `Not the Docs: content and voice on a developer blog `__ -- |:movie_camera:| `"You never get a second chance to make a first impression": writing great "getting started" documentation `__ -- |:movie_camera:| `Writing a book in 2017 `__ -- |:movie_camera:| `Do you know a runbook from a flip book? How sysadmins use documentation `__ +- |:movie_camera:| `The Facts About FAQs `__ +- |:movie_camera:| `Not the Docs: content and voice on a developer blog `__ +- |:movie_camera:| `"You never get a second chance to make a first impression": writing great "getting started" documentation `__ +- |:movie_camera:| `Writing a book in 2017 `__ +- |:movie_camera:| `Do you know a runbook from a flip book? How sysadmins use documentation `__ - |:newspaper:| `Maintaining command reference pages `__ -- |:movie_camera:| `Code the Docs: Interactive Document Environments `__ -- |:movie_camera:| `The Federated Wiki `__ -- |:movie_camera:| `Designing Information for Growth `__ +- |:movie_camera:| `Code the Docs: Interactive Document Environments `__ +- |:movie_camera:| `The Federated Wiki `__ +- |:movie_camera:| `Designing Information for Growth `__ - |:movie_camera:| `Blogging as Non-Traditional Support Documentation `__ - |:movie_camera:| `What I learned writing a lousy tech book `__ Storytelling ~~~~~~~~~~~~ -- |:movie_camera:| `When Wishing Still Helped … What Folklore Can Teach Us about Technical Writing `__ -- |:movie_camera:| `Storytelling for Technical Products - What We Can Learn from Lego and Pixar `__ -- |:movie_camera:| `Wild Geeks: Poetry in the Digital Age `__ -- |:movie_camera:| `Telling a Great Story on GitHub `__ -- |:movie_camera:| `What Writing Fiction Teaches You About Writing Documentation `__ -- |:movie_camera:| `Documenting your Story - Crafting a good presentation `__ -- |:movie_camera:| `Elevating the Hedgehog: Creativity in Tech Writing `__ -- |:movie_camera:| `Let’s Tell a Story: Scenario-Based Documentation `__ +- |:movie_camera:| `When Wishing Still Helped … What Folklore Can Teach Us about Technical Writing `__ +- |:movie_camera:| `Storytelling for Technical Products - What We Can Learn from Lego and Pixar `__ +- |:movie_camera:| `Wild Geeks: Poetry in the Digital Age `__ +- |:movie_camera:| `Telling a Great Story on GitHub `__ +- |:movie_camera:| `What Writing Fiction Teaches You About Writing Documentation `__ +- |:movie_camera:| `Documenting your Story - Crafting a good presentation `__ +- |:movie_camera:| `Elevating the Hedgehog: Creativity in Tech Writing `__ +- |:movie_camera:| `Let’s Tell a Story: Scenario-Based Documentation `__ Writing doc sets ---------------- - |:newspaper:| `Locked out: The effect on users from gated product docs `__ - |:newspaper:| `Public vs. private docs `__ -- |:movie_camera:| `Don’t shoot yourself in the foot with content reuse `__ -- |:movie_camera:| `How to launch your startup with good docs `__ -- |:movie_camera:| `Delivering Documents For All Three Use Cases `__ -- |:movie_camera:| `What nobody tells you about documentation `__ +- |:movie_camera:| `Don’t shoot yourself in the foot with content reuse `__ +- |:movie_camera:| `How to launch your startup with good docs `__ +- |:movie_camera:| `Delivering Documents For All Three Use Cases `__ +- |:movie_camera:| `What nobody tells you about documentation `__ Information architecture ~~~~~~~~~~~~~~~~~~~~~~~~ - |:newspaper:| `How to organize content in your documents `__ - |:newspaper:| `Where should support content live? `__ -- |:movie_camera:| `More than words: Reviewing and updating your information architecture `__ +- |:movie_camera:| `More than words: Reviewing and updating your information architecture `__ - |:newspaper:| `Organizing docs by role, or by topic? `__ - |:newspaper:| `A conversation about docs cleanup `__ - |:newspaper:| `Information architecture resources `__ - |:newspaper:| `Tagging docs `__ -- |:movie_camera:| `Building navigation for your doc site: 5 best practices `__ +- |:movie_camera:| `Building navigation for your doc site: 5 best practices `__ - |:newspaper:| `Navigation tabs for different audiences `__ -- |:movie_camera:| `Information micro-architecture: grammar, syntax, and cognitive rhetoric `__ +- |:movie_camera:| `Information micro-architecture: grammar, syntax, and cognitive rhetoric `__ - |:movie_camera:| `Search and find. How we made MDN discoverable `__ Legacy docs ~~~~~~~~~~~ - |:newspaper:| `Announcing Feature Deprecation `__ -- |:movie_camera:| `Organizing a Confluence hoard, or, does this page spark joy? `__ -- |:movie_camera:| `Legacy content from various perspectives `__ -- |:movie_camera:| `When Agile Fails: Working on Large Documentation Projects `__ -- |:movie_camera:| `How to tear down existing documentation and rewrite docs that actually work `__ -- |:movie_camera:| `Where do I start? The art and practice of documentation triage `__ -- |:movie_camera:| `Rewrite the Docs!: Field Notes from the Radical IT department `__ -- |:movie_camera:| `Deprecate and destroy: documenting your software’s last days `__ -- |:movie_camera:| `MacGyvering your docs `__ -- |:movie_camera:| `What Can Brownfield Do For You? `__ +- |:movie_camera:| `Organizing a Confluence hoard, or, does this page spark joy? `__ +- |:movie_camera:| `Legacy content from various perspectives `__ +- |:movie_camera:| `When Agile Fails: Working on Large Documentation Projects `__ +- |:movie_camera:| `How to tear down existing documentation and rewrite docs that actually work `__ +- |:movie_camera:| `Where do I start? The art and practice of documentation triage `__ +- |:movie_camera:| `Rewrite the Docs!: Field Notes from the Radical IT department `__ +- |:movie_camera:| `Deprecate and destroy: documenting your software’s last days `__ +- |:movie_camera:| `MacGyvering your docs `__ +- |:movie_camera:| `What Can Brownfield Do For You? `__ Maintenance ~~~~~~~~~~~ - |:newspaper:| `Strategies for successful documentation audits `__ -- |:movie_camera:| `Maintaining Documentation: Make It Easy! `__ +- |:movie_camera:| `Maintaining Documentation: Make It Easy! `__ - |:newspaper:| `Broken links and how to find them `__ -- |:movie_camera:| `Finding the line: Balancing business continuity and documentation debt `__ -- |:movie_camera:| `Future-Proofing Your Support Visuals `__ +- |:movie_camera:| `Finding the line: Balancing business continuity and documentation debt `__ +- |:movie_camera:| `Future-Proofing Your Support Visuals `__ - |:newspaper:| `When you find inaccuracies in your docs `__ - |:movie_camera:| `Making Yourself Redundant on Day One `__ - |:newspaper:| `Making docs maintainable `__ @@ -296,7 +296,7 @@ Jobs and careers - |:newspaper:| `What to do after surviving layoffs `__ - |:newspaper:| `Knowledge transfer for documentarians `__ - |:newspaper:| `Joining as a manager `__ -- |:movie_camera:| `Hustling for Fun and Profit as a Technical Writer: A Freelancing Starter Kit `__ +- |:movie_camera:| `Hustling for Fun and Profit as a Technical Writer: A Freelancing Starter Kit `__ - |:newspaper:| `Salary survey `__ - |:newspaper:| `For those who might consider freelancing `__ @@ -304,13 +304,13 @@ Hiring ~~~~~~~ - |:newspaper:| `Questions To Ask as an Interviewer `__ -- |:movie_camera:| `Fostering Technical Writing in Developing Nations `__ +- |:movie_camera:| `Fostering Technical Writing in Developing Nations `__ - |:newspaper:| `Using writing tests when hiring `__ - |:newspaper:| `Running objective interviews `__ - |:newspaper:| `Developer to documentarian ratio `__ - |:newspaper:| `Hiring and getting hired guide `__ -- |:movie_camera:| `Starting from Scratch: Finding and Hiring Junior Writers `__ -- |:movie_camera:| `Interviewing and hiring technical writers: the Siberian way `__ +- |:movie_camera:| `Starting from Scratch: Finding and Hiring Junior Writers `__ +- |:movie_camera:| `Interviewing and hiring technical writers: the Siberian way `__ - |:newspaper:| `Hiring for technical background `__ Getting hired @@ -326,7 +326,7 @@ Getting hired - |:newspaper:| `Job listings and managing your assumptions `__ - |:newspaper:| `Cover letters `__ - |:newspaper:| `Hiring and getting hired guide `__ -- |:movie_camera:| `Document Yourself: Practical Tips for a Low(er)-Stress Portfolio `__ +- |:movie_camera:| `Document Yourself: Practical Tips for a Low(er)-Stress Portfolio `__ - |:newspaper:| `Questions to ask at your job interview `__ - |:newspaper:| `More questions to ask at your job interview `__ - |:newspaper:| `Creating a doc portfolio `__ @@ -338,16 +338,16 @@ Related roles ~~~~~~~~~~~~~ - |:newspaper:| `Life After Documenting `__ -- |:movie_camera:| `Is Tech Writer a Tester, and Vice Versa, Is Tester a Tech Writer? `__ +- |:movie_camera:| `Is Tech Writer a Tester, and Vice Versa, Is Tester a Tech Writer? `__ - |:newspaper:| `A tale of two careers `__ -- |:movie_camera:| `What Writing Dictionaries Taught Me About Writing Documentation (And What I Had to Unlearn) `__ +- |:movie_camera:| `What Writing Dictionaries Taught Me About Writing Documentation (And What I Had to Unlearn) `__ - |:newspaper:| `Exploring other careers `__ - |:newspaper:| `Docs and content strategists `__ - |:newspaper:| `Developer relations/evangelism/advocacy `__ -- |:movie_camera:| `Caring Systems: Documentation as care `__ -- |:movie_camera:| `Operations Technical Writing for Data Centers `__ -- |:movie_camera:| `Beyond Software - Learning from Other Technical Writers `__ -- |:movie_camera:| `Oops, I Became an Engineer `__ +- |:movie_camera:| `Caring Systems: Documentation as care `__ +- |:movie_camera:| `Operations Technical Writing for Data Centers `__ +- |:movie_camera:| `Beyond Software - Learning from Other Technical Writers `__ +- |:movie_camera:| `Oops, I Became an Engineer `__ Career growth ~~~~~~~~~~~~~ @@ -359,29 +359,29 @@ Career growth - |:newspaper:| `Loneliness of the “Lone-ly” Documentarian `__ - |:newspaper:| `Is coding necessary to write good docs? `__ - |:newspaper:| `What’s in a (role) name, after all? `__ -- |:movie_camera:| `Beating the Virginia Blues: Thru-hiking strategies to help you survive your next big project `__ +- |:movie_camera:| `Beating the Virginia Blues: Thru-hiking strategies to help you survive your next big project `__ - |:newspaper:| `Taking steps into leadership `__ -- |:movie_camera:| `Docs leadership: How to become a stronger leader for your team `__ -- |:movie_camera:| `From travel content to technical content: my journey `__ +- |:movie_camera:| `Docs leadership: How to become a stronger leader for your team `__ +- |:movie_camera:| `From travel content to technical content: my journey `__ - |:newspaper:| `A magnificent array of management topics `__ -- |:movie_camera:| `From Graffiti Writer to Technical Writer `__ -- |:movie_camera:| `Overcoming the Plight of Lone Writers `__ +- |:movie_camera:| `From Graffiti Writer to Technical Writer `__ +- |:movie_camera:| `Overcoming the Plight of Lone Writers `__ - |:newspaper:| `Leading and following: finding a mentor, being a mentor `__ - |:newspaper:| `Feeling like a fraud and how to deal with it `__ -- |:movie_camera:| `Fostering Talent: Mentorship, Peer Reviews and Going Beyond Your Job Description `__ +- |:movie_camera:| `Fostering Talent: Mentorship, Peer Reviews and Going Beyond Your Job Description `__ - |:newspaper:| `Making the leap to managing writers `__ -- |:movie_camera:| `Writer? Editor? Teacher? `__ -- |:movie_camera:| `Harvest Past Experience to be a Great Tech Writer `__ +- |:movie_camera:| `Writer? Editor? Teacher? `__ +- |:movie_camera:| `Harvest Past Experience to be a Great Tech Writer `__ - |:newspaper:| `Tips for lone writers starting from scratch `__ - |:newspaper:| `Personal development goals `__ - |:newspaper:| `Career paths `__ - |:newspaper:| `Distinguishing between junior vs senior tech writers `__ - |:newspaper:| `Alternative titles to technical writer `__ - |:newspaper:| `Imposter syndrome `__ -- |:movie_camera:| `An Alien Looking From the Outside In: Main Takeaways After One Year in Documentation `__ +- |:movie_camera:| `An Alien Looking From the Outside In: Main Takeaways After One Year in Documentation `__ - |:newspaper:| `Job titles (real and imagined) `__ -- |:movie_camera:| `We’re Not in Kansas Anymore: How to Find Courage while Following the Technical Doc Road `__ -- |:movie_camera:| `IMPOSTER NO MORE: How Tech Writers Can Shed Self-Doubt, Embrace Uncertainty, and Surf the Upcoming Swerve in Technical Documentation `__ +- |:movie_camera:| `We’re Not in Kansas Anymore: How to Find Courage while Following the Technical Doc Road `__ +- |:movie_camera:| `IMPOSTER NO MORE: How Tech Writers Can Shed Self-Doubt, Embrace Uncertainty, and Surf the Upcoming Swerve in Technical Documentation `__ Building a team @@ -392,19 +392,19 @@ Including onboarding new writers - |:newspaper:| `Documentarians as Specialists or Generalists `__ - |:newspaper:| `Doc Team Organization `__ - |:newspaper:| `When less is NOT more `__ -- |:movie_camera:| `How I convinced my boss to build our docs team `__ -- |:movie_camera:| `From Me to Us: Building a docs team from the ground up `__ -- |:movie_camera:| `Level Up - Onboarding that enables writers to thrive `__ -- |:movie_camera:| `Onboard yourself: How to get set-up for success in a new role `__ +- |:movie_camera:| `How I convinced my boss to build our docs team `__ +- |:movie_camera:| `From Me to Us: Building a docs team from the ground up `__ +- |:movie_camera:| `Level Up - Onboarding that enables writers to thrive `__ +- |:movie_camera:| `Onboard yourself: How to get set-up for success in a new role `__ Learning... ~~~~~~~~~~~ - |:newspaper:| `Technical skills for documentarians `__ -- |:movie_camera:| `The Art of Asking Questions `__ +- |:movie_camera:| `The Art of Asking Questions `__ - |:newspaper:| `What we’re learning in #learn-tech-writing `__ -- |:movie_camera:| `Read the Rules: What technical writers can learn from board game design `__ +- |:movie_camera:| `Read the Rules: What technical writers can learn from board game design `__ - |:newspaper:| `Learning regular expressions (regex) `__ - |:newspaper:| `Book club: an intro to ‘Every Page is Page One’ `__ - |:newspaper:| `Learning material recommendations - fundamentals of tech writing, contenet strategy, API docs, Git `__ @@ -420,113 +420,113 @@ Design and UX Accessibility and inclusivity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- |:movie_camera:| `ADHD and its impact on the Creative Process for Writers `__ -- |:movie_camera:| `Writing Documentation with Neurodivergent Open Source Contributors In Mind `__ -- |:movie_camera:| `Moving beyond empathy: a11y in documentation `__ +- |:movie_camera:| `ADHD and its impact on the Creative Process for Writers `__ +- |:movie_camera:| `Writing Documentation with Neurodivergent Open Source Contributors In Mind `__ +- |:movie_camera:| `Moving beyond empathy: a11y in documentation `__ - |:newspaper:| `Resources for diverse example names `__ -- |:movie_camera:| `Inclusive environments are better: science says so `__ -- |:movie_camera:| `A11y-Friendly Documentation `__ +- |:movie_camera:| `Inclusive environments are better: science says so `__ +- |:movie_camera:| `A11y-Friendly Documentation `__ - |:newspaper:| `Accessibility for colour blindness `__ - |:newspaper:| `Screen readers and svgs `__ -- |:movie_camera:| `Sticks & Stones... Microaggressions & Inclusive Language at Work `__ +- |:movie_camera:| `Sticks & Stones... Microaggressions & Inclusive Language at Work `__ - |:newspaper:| `Alt text best practices `__ - |:newspaper:| `Improving diversity in docs `__ - |:newspaper:| `Responsible communication guide `__ -- |:movie_camera:| `Accessible Math on the Web: A Server/Client Solution `__ -- |:movie_camera:| `Inclusive Tech Docs - TechComm Meets Accessibility `__ +- |:movie_camera:| `Accessible Math on the Web: A Server/Client Solution `__ +- |:movie_camera:| `Inclusive Tech Docs - TechComm Meets Accessibility `__ Localization and globalization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- |:movie_camera:| `Creating documentation for the African audience `__ -- |:movie_camera:| `Toward the broader globalization of Open Source: documenting your localisation Journey `__ -- |:movie_camera:| `How I use applied linguistics to be a better technical writer `__ -- |:movie_camera:| `Influence your customer outreach with best practices for internationalization `__ -- |:movie_camera:| `Globalise the docs `__ -- |:movie_camera:| `Found in Translation: Lessons from a Year of Open Source Localization `__ -- |:movie_camera:| `Localize the Docs! `__ +- |:movie_camera:| `Creating documentation for the African audience `__ +- |:movie_camera:| `Toward the broader globalization of Open Source: documenting your localisation Journey `__ +- |:movie_camera:| `How I use applied linguistics to be a better technical writer `__ +- |:movie_camera:| `Influence your customer outreach with best practices for internationalization `__ +- |:movie_camera:| `Globalise the docs `__ +- |:movie_camera:| `Found in Translation: Lessons from a Year of Open Source Localization `__ +- |:movie_camera:| `Localize the Docs! `__ Design ~~~~~~~ -- |:movie_camera:| `When documenting is designing: How to assist API design as a technical writer `__ -- |:movie_camera:| `Surprise! You’re a designer now. `__ +- |:movie_camera:| `When documenting is designing: How to assist API design as a technical writer `__ +- |:movie_camera:| `Surprise! You’re a designer now. `__ - |:newspaper:| `Docs and design: When docs can’t fix all the things `__ -- |:movie_camera:| `How I decided to do this talk `__ -- |:movie_camera:| `Peanuts and Minimalism and Technical Writing `__ -- |:movie_camera:| `Writing for what matters. Writing for thinking. `__ -- |:movie_camera:| `We Are All Abbott and Costello `__ -- |:movie_camera:| `Designing Information for Growth `__ +- |:movie_camera:| `How I decided to do this talk https://www.youtube.com/watch?v=iWvAXHCfF1A`__ +- |:movie_camera:| `Peanuts and Minimalism and Technical Writing `__ +- |:movie_camera:| `Writing for what matters. Writing for thinking. `__ +- |:movie_camera:| `We Are All Abbott and Costello `__ +- |:movie_camera:| `Designing Information for Growth `__ - |:movie_camera:| `advanced web typography `__ UX writing ~~~~~~~~~~ - |:newspaper:| `Edge cases and when (and where!) to document them `__ -- |:movie_camera:| `Invisible influence — the documentation behind UX copy `__ -- |:movie_camera:| `Little words, big ideas: How to write microcopy that works `__ +- |:movie_camera:| `Invisible influence — the documentation behind UX copy `__ +- |:movie_camera:| `Little words, big ideas: How to write microcopy that works `__ - |:movie_camera:| `UX Writing - Let Your Product Speak `__ - |:movie_camera:| `Creating experiences with information `__ -- |:movie_camera:| `Conversational UI for Writers `__ +- |:movie_camera:| `Conversational UI for Writers `__ - |:newspaper:| `Enforcing UI style guides `__ - |:newspaper:| `Auditing UI text `__ - |:newspaper:| `Writing error messages `__ -- |:movie_camera:| `Error Messages: Being Humble, Human, and Helpful will make users Happy `__ +- |:movie_camera:| `Error Messages: Being Humble, Human, and Helpful will make users Happy `__ - |:newspaper:| `Docs and content strategists `__ - |:newspaper:| `What to include in UI copy `__ -- |:movie_camera:| `Using meaningful names to improve API-documentation `__ -- |:movie_camera:| `Watch that tone! Creating an information experience in the Atlassian voice `__ -- |:movie_camera:| `Copy That: Helping your Users Succeed with Effective Product Copy `__ -- |:movie_camera:| `Atlassian: My Information Experience Adventure `__ -- |:movie_camera:| `Before the docs: writing for user interfaces `__ -- |:movie_camera:| `Keep ‘em playing `__ +- |:movie_camera:| `Using meaningful names to improve API-documentation `__ +- |:movie_camera:| `Watch that tone! Creating an information experience in the Atlassian voice `__ +- |:movie_camera:| `Copy That: Helping your Users Succeed with Effective Product Copy `__ +- |:movie_camera:| `Atlassian: My Information Experience Adventure `__ +- |:movie_camera:| `Before the docs: writing for user interfaces `__ +- |:movie_camera:| `Keep ‘em playing `__ Doc site design ~~~~~~~~~~~~~~~ -- |:movie_camera:| `A treasure map for the doc – Exploring the discoverability of documentation `__ -- |:movie_camera:| `Disagree with “I Agree”. Enforcing better data privacy through the language of documentation `__ +- |:movie_camera:| `A treasure map for the doc – Exploring the discoverability of documentation `__ +- |:movie_camera:| `Disagree with “I Agree”. Enforcing better data privacy through the language of documentation `__ - |:movie_camera:| `Responsive Content - Presenting Your information On Any Device `__ - |:newspaper:| `"Last updated" in docs `__ - |:newspaper:| `Documentation bylines `__ - |:newspaper:| `Meaningful URLs `__ - |:newspaper:| `API reference docs layout `__ -- |:movie_camera:| `Code the Docs: Interactive Document Environments `__ +- |:movie_camera:| `Code the Docs: Interactive Document Environments `__ - |:newspaper:| `Can form follow function in techdoc? `__ User needs ~~~~~~~~~~ -- |:movie_camera:| `The Baseline – Or Technical Writing for Non-Technical Readers `__ -- |:movie_camera:| `Seeing your docs through different eyes: Mapping doc users’ experiences `__ -- |:movie_camera:| `Documenting known unknowns `__ -- |:movie_camera:| `Requirements that you didn't know were there `__ -- |:movie_camera:| `As Good As It Gets: Why Better Trumps Best `__ -- |:movie_camera:| `API documentation: Exploring the information needs of software developers `__ -- |:movie_camera:| `Documentation with Human Connection `__ -- |:movie_camera:| `User-Story Driven Docs `__ +- |:movie_camera:| `The Baseline – Or Technical Writing for Non-Technical Readers `__ +- |:movie_camera:| `Seeing your docs through different eyes: Mapping doc users’ experiences `__ +- |:movie_camera:| `Documenting known unknowns `__ +- |:movie_camera:| `Requirements that you didn't know were there `__ +- |:movie_camera:| `As Good As It Gets: Why Better Trumps Best `__ +- |:movie_camera:| `API documentation: Exploring the information needs of software developers `__ +- |:movie_camera:| `Documentation with Human Connection `__ +- |:movie_camera:| `User-Story Driven Docs `__ Doc tools --------- - |:newspaper:| `Choosing a CCMS or a static site generator `__ -- |:movie_camera:| `Two years of Markdoc: what we’ve learned about balancing developer and author experience `__ +- |:movie_camera:| `Two years of Markdoc: what we’ve learned about balancing developer and author experience `__ - |:newspaper:| `Standards in documentation tooling `__ -- |:movie_camera:| `Putting the “tech” in technical writer `__ -- |:movie_camera:| `Documentation as an application: enabling interactive content that is tailored to the user `__ -- |:movie_camera:| `Model-view-docs: taming large-scale documentation projects using structured data `__ -- |:movie_camera:| `The Rocky Road to DocOps `__ -- |:movie_camera:| `Don’t Fear Migration! How to Successfully Move Docs to a New Tool `__ -- |:movie_camera:| `Where Documentation, Cloud-hosted Interactive Tutorials and Continuous Integration Testing Intersect `__ +- |:movie_camera:| `Putting the “tech” in technical writer `__ +- |:movie_camera:| `Documentation as an application: enabling interactive content that is tailored to the user `__ +- |:movie_camera:| `Model-view-docs: taming large-scale documentation projects using structured data `__ +- |:movie_camera:| `The Rocky Road to DocOps `__ +- |:movie_camera:| `Don’t Fear Migration! How to Successfully Move Docs to a New Tool `__ +- |:movie_camera:| `Where Documentation, Cloud-hosted Interactive Tutorials and Continuous Integration Testing Intersect `__ - |:newspaper:| `How your tools affect your writing `__ - |:newspaper:| `Deciding on a new tool… `__ - |:newspaper:| `… and migrating to a new tool `__ -- |:movie_camera:| `How I Learned to Stop Worrying and Love the Command Line `__ -- |:movie_camera:| `Choosing a tool... and choosing your moment `__ -- |:movie_camera:| `Writing extensions in Sphinx: supercharge your docs `__ -- |:movie_camera:| `Finally! Trustworthy and Sensible API Documentation with GraphQL `__ -- |:movie_camera:| `Embed The Docs `__ +- |:movie_camera:| `How I Learned to Stop Worrying and Love the Command Line `__ +- |:movie_camera:| `Choosing a tool... and choosing your moment `__ +- |:movie_camera:| `Writing extensions in Sphinx: supercharge your docs `__ +- |:movie_camera:| `Finally! Trustworthy and Sensible API Documentation with GraphQL `__ +- |:movie_camera:| `Embed The Docs `__ - |:newspaper:| `Toolchains for docs `__ - |:movie_camera:| `Challenges and approaches taken with the Opera Extension Docs `__ - |:movie_camera:| `Writing multi-language documentation using Sphinx `__ @@ -543,10 +543,10 @@ Docs-as-code - |:newspaper:| `Drafting Docs with Code Changes `__ - |:newspaper:| `Docs with Code Or Just as Code? `__ - |:newspaper:| `Semantic Linefeeds `__ -- |:movie_camera:| `One AWS team’s move to docs as code: what worked, what didn’t, what’s next `__ +- |:movie_camera:| `One AWS team’s move to docs as code: what worked, what didn’t, what’s next `__ - |:newspaper:| `To git or not to git docs as code `__ - |:newspaper:| `Pros and cons of the docs-as-code approach `__ -- |:movie_camera:| `The UK government meets docs as code `__ +- |:movie_camera:| `The UK government meets docs as code `__ - |:newspaper:| `Adventures in generating docs from code comments `__ - |:newspaper:| `What to do about text wrapping `__ - |:newspaper:| `DITA vs docs-as-code `__ @@ -556,12 +556,12 @@ Docs-as-code - |:newspaper:| `Versioning docs with docs as code `__ - |:newspaper:| `Making docs maintainable `__ - |:newspaper:| `What are static site generators? `__ -- |:movie_camera:| `Treating documentation like code: a practical account `__ +- |:movie_camera:| `Treating documentation like code: a practical account `__ - |:newspaper:| `Making Atom (even) better `__ - |:newspaper:| `Tricks for static sites `__ -- |:movie_camera:| `Docs as Code: The Missing Manual `__ -- |:movie_camera:| `A Developers’ Approach to Documentation: From Passive to Dynamic `__ -- |:movie_camera:| `How GitHub uses GitHub to document GitHub `__ +- |:movie_camera:| `Docs as Code: The Missing Manual `__ +- |:movie_camera:| `A Developers’ Approach to Documentation: From Passive to Dynamic `__ +- |:movie_camera:| `How GitHub uses GitHub to document GitHub `__ DITA ~~~~~~~ @@ -587,14 +587,14 @@ Automation ~~~~~~~~~~ - |:newspaper:| `Link-checking tools `__ -- |:movie_camera:| `Unit Test the Docs: Why You Should Test Your Code Examples `__ -- |:movie_camera:| `Beyond spell checking - what else can we check automatically? `__ -- |:movie_camera:| `Run your documentation `__ +- |:movie_camera:| `Unit Test the Docs: Why You Should Test Your Code Examples `__ +- |:movie_camera:| `Beyond spell checking - what else can we check automatically? `__ +- |:movie_camera:| `Run your documentation `__ - |:newspaper:| `Automated screenshot-taking `__ -- |:movie_camera:| `Testing: it's not just for code anymore `__ -- |:movie_camera:| `Tech writing in a continuous deployment world `__ -- |:movie_camera:| `Tested and Correct, How to Make Sure Your Documentation Keeps Working `__ -- |:movie_camera:| `Generating docs from APIs `__ +- |:movie_camera:| `Testing: it's not just for code anymore `__ +- |:movie_camera:| `Tech writing in a continuous deployment world `__ +- |:movie_camera:| `Tested and Correct, How to Make Sure Your Documentation Keeps Working `__ +- |:movie_camera:| `Generating docs from APIs `__ - |:newspaper:| `Automation dreams - and realities `__ Git @@ -608,8 +608,8 @@ Search ~~~~~~~ - |:newspaper:| `SEO for docs: How much and how? `__ -- |:movie_camera:| `The Search for Search `__ -- |:movie_camera:| `Making documentation discoverable in search engines `__ +- |:movie_camera:| `The Search for Search `__ +- |:movie_camera:| `Making documentation discoverable in search engines `__ Metrics and analytics @@ -617,21 +617,21 @@ Metrics and analytics - |:newspaper:| `Gaining Insight from Docs Metrics `__ - |:newspaper:| `Discovering user needs `__ -- |:movie_camera:| `Don’t trust the numbers! `__ -- |:movie_camera:| `The Importance of Using Analytics and Feedback for your Documentation `__ +- |:movie_camera:| `Don’t trust the numbers! `__ +- |:movie_camera:| `The Importance of Using Analytics and Feedback for your Documentation `__ User research ~~~~~~~~~~~~~ -- |:movie_camera:| `Walking Backwards: Tracing the New Customer Journey from Finish to Start to Help Shape Content `__ +- |:movie_camera:| `Walking Backwards: Tracing the New Customer Journey from Finish to Start to Help Shape Content `__ - |:newspaper:| `Starting out with analytics - and then upping your game `__ - |:newspaper:| `Discovering user needs `__ -- |:movie_camera:| `Research like you’re wrong: Lessons from user research gone rogue `__ -- |:movie_camera:| `Building Empathy-Driven Developer Documentation `__ +- |:movie_camera:| `Research like you’re wrong: Lessons from user research gone rogue `__ +- |:movie_camera:| `Building Empathy-Driven Developer Documentation `__ - |:newspaper:| `UX testing documentation `__ -- |:movie_camera:| `API documentation: Exploring the information needs of software developers `__ -- |:movie_camera:| `We Are All Abbott and Costello `__ -- |:movie_camera:| `How to Write Documentation for People that Don't Read `__ +- |:movie_camera:| `API documentation: Exploring the information needs of software developers `__ +- |:movie_camera:| `We Are All Abbott and Costello `__ +- |:movie_camera:| `How to Write Documentation for People that Don't Read `__ User feedback ~~~~~~~~~~~~~ @@ -640,12 +640,12 @@ Gathering it and acting on it. - |:newspaper:| `Managing mountains of feedback `__ - |:newspaper:| `Collecting helpful user feedback `__ -- |:movie_camera:| `Customer Feedback is the Fuel in our Engine `__ +- |:movie_camera:| `Customer Feedback is the Fuel in our Engine `__ - |:newspaper:| `Gathering documentation feedback `__ - |:newspaper:| `Documentation feedback widgets - thumbs up or down? `__ - |:newspaper:| `Collecting and acting on user feedback `__ - |:newspaper:| `Gathering user feedback `__ -- |:movie_camera:| `CSAT - What's That? `__ +- |:movie_camera:| `CSAT - What's That? `__ Measuring docs success @@ -653,7 +653,7 @@ Measuring docs success - |:newspaper:| `Measuring Docs Effect on User Experience `__ - |:newspaper:| `Measuring productivity of docs teams `__ -- |:movie_camera:| `Measuring Documentation Success in Open Source: Findings from Google’s Season of Docs Program `__ +- |:movie_camera:| `Measuring Documentation Success in Open Source: Findings from Google’s Season of Docs Program `__ - |:newspaper:| `Objectives and key results (OKRs) for documentation `__ - |:newspaper:| `A/B testing docs `__ @@ -663,7 +663,7 @@ Metrics - |:newspaper:| `How to think about docs metrics `__ - |:newspaper:| `Do Readability Scores Have Value? `__ - |:newspaper:| `Measuring Docs Quality `__ -- |:movie_camera:| `Measuring the impact of your documentation `__ +- |:movie_camera:| `Measuring the impact of your documentation `__ - |:newspaper:| `Documentation metrics `__ - |:newspaper:| `More on metrics `__ - |:newspaper:| `Case study: Total Time Reading `__ @@ -673,58 +673,58 @@ Culture and community - |:newspaper:| `The benefits of networking `__ - |:movie_camera:| `Dealing with Unpleasant People in Open-Source Projects `__ -- |:movie_camera:| `A guide to getting started in open source `__ -- |:movie_camera:| `5 things I learned from my first open source contribution `__ -- |:movie_camera:| `A Year in the Life of The Better Docs Project `__ -- |:movie_camera:| `Technical writing as public service: working on open source in government `__ +- |:movie_camera:| `A guide to getting started in open source `__ +- |:movie_camera:| `5 things I learned from my first open source contribution `__ +- |:movie_camera:| `A Year in the Life of The Better Docs Project `__ +- |:movie_camera:| `Technical writing as public service: working on open source in government `__ Building docs culture ~~~~~~~~~~~~~~~~~~~~~ - |:newspaper:| `Motivating Contributions to Internal Docs `__ - |:newspaper:| `The importance of docs... in 30 minutes `__ -- |:movie_camera:| `Adventures in setting up a knowledge system for a research group `__ -- |:movie_camera:| `Almost None to Some: Driving DISQO’s Doc Culture as a Solo Documentarian `__ -- |:movie_camera:| `How to be an Avante-Garde Guinea Pig: Building Better Content through Experimentation, Community-building, and Loud Squeaks `__ -- |:movie_camera:| `Everyone’s a player (in a mid-90s MUD) `__ -- |:movie_camera:| `Documenting for Open Source `__ -- |:movie_camera:| `Defying the Status Quo: How a grassroots effort can transform an organization `__ -- |:movie_camera:| `Sponsored Talk: Documentation for Good: Knowledge as a tool for equity and inclusion `__ +- |:movie_camera:| `Adventures in setting up a knowledge system for a research group `__ +- |:movie_camera:| `Almost None to Some: Driving DISQO’s Doc Culture as a Solo Documentarian `__ +- |:movie_camera:| `How to be an Avante-Garde Guinea Pig: Building Better Content through Experimentation, Community-building, and Loud Squeaks `__ +- |:movie_camera:| `Everyone’s a player (in a mid-90s MUD) `__ +- |:movie_camera:| `Documenting for Open Source `__ +- |:movie_camera:| `Defying the Status Quo: How a grassroots effort can transform an organization `__ +- |:movie_camera:| `Sponsored Talk: Documentation for Good: Knowledge as a tool for equity and inclusion `__ - |:newspaper:| `Promoting plain language `__ - |:newspaper:| `Common misconceptions about docs `__ -- |:movie_camera:| `Who Writes the Docs? `__ +- |:movie_camera:| `Who Writes the Docs? `__ - |:newspaper:| `Help your contributors help your project `__ - |:newspaper:| `Crowdsourcing docs `__ -- |:movie_camera:| `Everyone's a player (in a mid-90s MUD) `__ -- |:movie_camera:| `Move Fast And Document Things: Hard-Won Lessons in Building Documentation Culture in Startups `__ -- |:movie_camera:| `All roads might not lead to docs `__ -- |:movie_camera:| `Free Your Mind and Your Docs Will Follow `__ -- |:movie_camera:| `Documentation, Disrupted How Two Technical Writers Changed Google Engineering Culture, Built a Team, Made Powerful Friends, And Got Their Mojo Back `__ -- |:movie_camera:| `Entry points and guide posts: Helping new contributors find their way `__ -- |:movie_camera:| `The Making of Writing Black Belts: How Martial Arts Philosophy Forged an Ad-Hoc Writing Team that Writes Great Docs `__ +- |:movie_camera:| `Everyone's a player (in a mid-90s MUD) `__ +- |:movie_camera:| `Move Fast And Document Things: Hard-Won Lessons in Building Documentation Culture in Startups `__ +- |:movie_camera:| `All roads might not lead to docs `__ +- |:movie_camera:| `Free Your Mind and Your Docs Will Follow `__ +- |:movie_camera:| `Documentation, Disrupted How Two Technical Writers Changed Google Engineering Culture, Built a Team, Made Powerful Friends, And Got Their Mojo Back `__ +- |:movie_camera:| `Entry points and guide posts: Helping new contributors find their way `__ +- |:movie_camera:| `The Making of Writing Black Belts: How Martial Arts Philosophy Forged an Ad-Hoc Writing Team that Writes Great Docs `__ Building community ~~~~~~~~~~~~~~~~~~ -- |:movie_camera:| `Peer writing and beyond - An experimental approach to a sustainable open-source projects `__ -- |:movie_camera:| `All together now: Turning technologists into documentarians `__ -- |:movie_camera:| `Documentation Communities: Sound Strategy or Documentarian’s Gambit? `__ -- |:movie_camera:| `Helping Your Community Contribute to Developer Documentation `__ -- |:movie_camera:| `Any friend of the docs is a friend of mine: Cultivating a community of documentation advocates `__ -- |:movie_camera:| `A content manager's guide to crowdsourcing the docs `__ -- |:movie_camera:| `No Community Members Were Harmed in the Making of This Doc Sprint `__ -- |:movie_camera:| `The Wisdom of Crowds: Crowdsourcing Minimalism in an Open Organization `__ -- |:movie_camera:| `Feedback handling, community wrangling, panhandling `__ -- |:movie_camera:| `Documentoring: Growing a "Love The Docs" community `__ -- |:movie_camera:| `How to Publish Wild-Caught Articles `__ -- |:movie_camera:| `Gardening Open Docs `__ +- |:movie_camera:| `Peer writing and beyond - An experimental approach to a sustainable open-source projects `__ +- |:movie_camera:| `All together now: Turning technologists into documentarians `__ +- |:movie_camera:| `Documentation Communities: Sound Strategy or Documentarian’s Gambit? `__ +- |:movie_camera:| `Helping Your Community Contribute to Developer Documentation `__ +- |:movie_camera:| `Any friend of the docs is a friend of mine: Cultivating a community of documentation advocates `__ +- |:movie_camera:| `A content manager's guide to crowdsourcing the docs `__ +- |:movie_camera:| `No Community Members Were Harmed in the Making of This Doc Sprint `__ +- |:movie_camera:| `The Wisdom of Crowds: Crowdsourcing Minimalism in an Open Organization `__ +- |:movie_camera:| `Feedback handling, community wrangling, panhandling `__ +- |:movie_camera:| `Documentoring: Growing a "Love The Docs" community `__ +- |:movie_camera:| `How to Publish Wild-Caught Articles `__ +- |:movie_camera:| `Gardening Open Docs `__ - |:movie_camera:| `The community wrote my docs! `__ Meetups ~~~~~~~ - |:newspaper:| `Framework for meetups `__ -- |:movie_camera:| `Start Your Own Write the Docs Meetup Group `__ +- |:movie_camera:| `Start Your Own Write the Docs Meetup Group `__ Style guides ~~~~~~~~~~~~ @@ -732,22 +732,22 @@ Style guides - |:newspaper:| `Create a screenshot style guide `__ - |:newspaper:| `Choosing a style guide `__ - |:movie_camera:| `The Art of Consistency: Creating an in-house style guide `__ -- |:movie_camera:| `Building a style guide from the ground up: lessons learned from a lone writer `__ -- |:movie_camera:| `What They Don't Tell You About Creating New Style Guides `__ +- |:movie_camera:| `Building a style guide from the ground up: lessons learned from a lone writer `__ +- |:movie_camera:| `What They Don't Tell You About Creating New Style Guides `__ - |:newspaper:| `Enforcing UI style guides `__ - |:newspaper:| `Style guides we like `__ - |:newspaper:| `Improving diversity in docs `__ - |:newspaper:| `Responsible communication guide `__ - |:newspaper:| `One style guide for all types of writing? `__ -- |:movie_camera:| `Watch that tone! Creating an information experience in the Atlassian voice `__ -- |:movie_camera:| `Whatchamacallit: Controlled Vocabularies for Technical Writers `__ +- |:movie_camera:| `Watch that tone! Creating an information experience in the Atlassian voice `__ +- |:movie_camera:| `Whatchamacallit: Controlled Vocabularies for Technical Writers `__ Working across roles -------------------- - |:newspaper:| `Keeping cool when challenged `__ - |:newspaper:| `Behavior in text vs in person in the workplace `__ -- |:movie_camera:| `Cultivating a Stakeholder Network for Our Docs: How Building Relationships Improves Our Content `__ +- |:movie_camera:| `Cultivating a Stakeholder Network for Our Docs: How Building Relationships Improves Our Content `__ - |:newspaper:| `The strengths of different backgrounds `__ Working with writers @@ -758,32 +758,32 @@ Including review, editing, and teaching. - |:newspaper:| `Optimal number of reviewers `__ - |:newspaper:| `Getting it right: Constructive criticism `__ - |:newspaper:| `What’s in a good reviewer’s guide? `__ -- |:movie_camera:| `Code Cowpokes and Word Wranglers: from Mutual Admiration to Solidarity `__ -- |:movie_camera:| `The Pains of Composition: How to write your best documentation in a collaborative world `__ +- |:movie_camera:| `Code Cowpokes and Word Wranglers: from Mutual Admiration to Solidarity `__ +- |:movie_camera:| `The Pains of Composition: How to write your best documentation in a collaborative world `__ - |:newspaper:| `The challenge of giving difficult feedback `__ - |:newspaper:| `Facilitating top-notch doc review `__ -- |:movie_camera:| `How to edit other people’s content without pissing them off `__ +- |:movie_camera:| `How to edit other people’s content without pissing them off `__ - |:movie_camera:| `Good Code, Bad Code & Code Review `__ - |:newspaper:| `Giving feedback `__ - |:newspaper:| `Teaching peers writing `__ -- |:movie_camera:| `You have already succeeded: Design critique guidelines make feedback easier `__ -- |:movie_camera:| `How GitHub uses GitHub to document GitHub `__ +- |:movie_camera:| `You have already succeeded: Design critique guidelines make feedback easier `__ +- |:movie_camera:| `How GitHub uses GitHub to document GitHub `__ Customer support ~~~~~~~~~~~~~~~~ - |:newspaper:| `Supporting documentation, documenting support `__ - |:movie_camera:| `Power up your support team to create better documentation `__ -- |:movie_camera:| `Only Interesting Conversations: The symbiotic relationship between docs and support `__ -- |:movie_camera:| `Documentarians and Support: Work Better Together `__ -- |:movie_camera:| `Two Great Teams that Work Better Together: Bridging the Gap Between Documentation and Customer Support `__ +- |:movie_camera:| `Only Interesting Conversations: The symbiotic relationship between docs and support `__ +- |:movie_camera:| `Documentarians and Support: Work Better Together `__ +- |:movie_camera:| `Two Great Teams that Work Better Together: Bridging the Gap Between Documentation and Customer Support `__ Helping engineers to write ~~~~~~~~~~~~~~~~~~~~~~~~~~ - |:newspaper:| `Tactics for motivating docs contributions `__ - |:newspaper:| `The engineer and the writer can be friends: tales of collaboration `__ -- |:movie_camera:| `Teaching geeks to fish: tales of a contagious documentarian `__ +- |:movie_camera:| `Teaching geeks to fish: tales of a contagious documentarian `__ - |:newspaper:| `Promoting plain language `__ - |:newspaper:| `Teaching peers writing `__ - |:newspaper:| `Giving feedback `__ @@ -804,16 +804,16 @@ Including product managers, higher-ups, etc. - |:newspaper:| `Setting boundaries `__ - |:newspaper:| `Push vs. pull for docs work `__ - |:newspaper:| `Improving communication about what's in releases `__ -- |:movie_camera:| `Documentation as Marketing? From Conflict to Collaboration `__ -- |:movie_camera:| `Collaborating with teams on content strategy planning: pitfalls and best practices `__ +- |:movie_camera:| `Documentation as Marketing? From Conflict to Collaboration `__ +- |:movie_camera:| `Collaborating with teams on content strategy planning: pitfalls and best practices `__ - |:newspaper:| `Getting more info from SMEs `__ -- |:movie_camera:| `An introduction to developer experience, and the role of a documentarian `__ +- |:movie_camera:| `An introduction to developer experience, and the role of a documentarian `__ - |:movie_camera:| `The subtle art of interrogation `__ - |:newspaper:| `Helping project managers understand docs `__ - |:newspaper:| `Conflicts about what should be in the docs `__ - |:newspaper:| `Writing good bug reports `__ -- |:movie_camera:| `Crossing the Streams: Enabling Collaboration Between Products and Upstreams `__ -- |:movie_camera:| `Writer, Meet Tester `__ +- |:movie_camera:| `Crossing the Streams: Enabling Collaboration Between Products and Upstreams `__ +- |:movie_camera:| `Writer, Meet Tester `__ - |:movie_camera:| `Pairing with designers to create a seamless user experience `__ Planning and how we work @@ -823,12 +823,12 @@ Planning and how we work - |:newspaper:| `Keeping Up-To-Date with Necessary Changes `__ - |:newspaper:| `Estimating docs work `__ - |:newspaper:| `Estimating work `__ -- |:movie_camera:| `Alchemy in Adversity (How to become better and more resilient tech writers in a turbulent work environment) `__ +- |:movie_camera:| `Alchemy in Adversity (How to become better and more resilient tech writers in a turbulent work environment) `__ - |:newspaper:| `Adapting to working from home `__ -- |:movie_camera:| `Remote Job On-boarding: Top 10 Things We Can Do (Better) `__ +- |:movie_camera:| `Remote Job On-boarding: Top 10 Things We Can Do (Better) `__ - |:newspaper:| `The costs of outdated docs `__ - |:newspaper:| `How to set priorities on a documentation team `__ -- |:movie_camera:| `The Super Effective Writing Process of Grammy-winning Artists `__ +- |:movie_camera:| `The Super Effective Writing Process of Grammy-winning Artists `__ - |:newspaper:| `Writing remotely `__ - |:newspaper:| `Roadmaps and documenting 'future features' `__ @@ -837,9 +837,9 @@ Prioritisation - |:newspaper:| `Pushing Back When You're Overloaded `__ - |:newspaper:| `Dealing with competing priorities `__ -- |:movie_camera:| `Just Add Data: Make it easier to prioritize your documentation `__ -- |:movie_camera:| `Document What Matters: Lean Best Practice for Process Documentation `__ -- |:movie_camera:| `Where do I start? The art and practice of documentation triage `__ +- |:movie_camera:| `Just Add Data: Make it easier to prioritize your documentation `__ +- |:movie_camera:| `Document What Matters: Lean Best Practice for Process Documentation `__ +- |:movie_camera:| `Where do I start? The art and practice of documentation triage `__ Agile and workflows ~~~~~~~~~~~~~~~~~~~ @@ -847,69 +847,69 @@ Agile and workflows - |:newspaper:| `Delay releases or publish docs late `__ - |:newspaper:| `Navigating Agile for documentarians `__ - |:newspaper:| `Tracking work `__ -- |:movie_camera:| `Documenting the (Ancient) History of Your Project `__ -- |:movie_camera:| `Building a content-focused, scientific document authoring workflow for Data Scientists and Engineers alike `__ -- |:movie_camera:| `Lessons Learned in a Year of Docs-Driven Development `__ +- |:movie_camera:| `Documenting the (Ancient) History of Your Project `__ +- |:movie_camera:| `Building a content-focused, scientific document authoring workflow for Data Scientists and Engineers alike `__ +- |:movie_camera:| `Lessons Learned in a Year of Docs-Driven Development `__ - |:newspaper:| `Task management for docs teams `__ - |:newspaper:| `Agile workflows for docs `__ - |:newspaper:| `Working on Agile teams `__ - |:newspaper:| `Changing docs workflows `__ - |:newspaper:| `Automating routine tasks `__ -- |:movie_camera:| `Postulating The Backlog Laxative `__ -- |:movie_camera:| `Judas Priest Ate My Scrum Master `__ +- |:movie_camera:| `Postulating The Backlog Laxative `__ +- |:movie_camera:| `Judas Priest Ate My Scrum Master `__ - |:movie_camera:| `Your Personal Tech-Writing Agile Manifesto (or: Scrum is not a 4-character word) `__ Continuous delivery ~~~~~~~~~~~~~~~~~~~ - |:newspaper:| `Agile delivery and continuous releases `__ -- |:movie_camera:| `Delivering High-Velocity Docs that Keep Pace with Rapid Release Cycles `__ -- |:movie_camera:| `Continuous Annoyment: Bringing More Zen to a Hectic Writing Environment `__ -- |:movie_camera:| `Just-In-Time Documentation: Employing Agile Methodology To Create Living Documentation `__ +- |:movie_camera:| `Delivering High-Velocity Docs that Keep Pace with Rapid Release Cycles `__ +- |:movie_camera:| `Continuous Annoyment: Bringing More Zen to a Hectic Writing Environment `__ +- |:movie_camera:| `Just-In-Time Documentation: Employing Agile Methodology To Create Living Documentation `__ - |:movie_camera:| `Keeping trust: Testing documentation as part of a continuous integration process `__ Strategy ~~~~~~~~ -- |:movie_camera:| `Lessons Learned from Cloud Ops: Writing Docs for High-Stakes Situations `__ -- |:movie_camera:| `Always complete, never finished `__ -- |:movie_camera:| `Beyond metrics: Using maturity models to develop a docs strategy `__ -- |:movie_camera:| `Content strategy in practice: a case study `__ -- |:movie_camera:| `Show Me the Money: How to Get Your Docs the Love and Support They Deserve `__ +- |:movie_camera:| `Lessons Learned from Cloud Ops: Writing Docs for High-Stakes Situations `__ +- |:movie_camera:| `Always complete, never finished `__ +- |:movie_camera:| `Beyond metrics: Using maturity models to develop a docs strategy `__ +- |:movie_camera:| `Content strategy in practice: a case study `__ +- |:movie_camera:| `Show Me the Money: How to Get Your Docs the Love and Support They Deserve `__ - |:movie_camera:| `Backseat content strategy `__ -- |:movie_camera:| `Product Documentation Strategy: What Is It and Why Do We Need It? `__ -- |:movie_camera:| `Choosing a tool... and choosing your moment `__ -- |:movie_camera:| `Audience, Market, Product: Tips for strategic API documentation planning `__ -- |:movie_camera:| `Bootstrapping Docs at a Startup `__ +- |:movie_camera:| `Product Documentation Strategy: What Is It and Why Do We Need It? `__ +- |:movie_camera:| `Choosing a tool... and choosing your moment `__ +- |:movie_camera:| `Audience, Market, Product: Tips for strategic API documentation planning `__ +- |:movie_camera:| `Bootstrapping Docs at a Startup `__ - |:newspaper:| `Making docs maintainable `__ -- |:movie_camera:| `Designing Information for Growth `__ +- |:movie_camera:| `Designing Information for Growth `__ Defining success ~~~~~~~~~~~~~~~~ -- |:movie_camera:| `As Good As It Gets: Why Better Trumps Best `__ -- |:movie_camera:| `Success is More Than Not Failing `__ +- |:movie_camera:| `As Good As It Gets: Why Better Trumps Best `__ +- |:movie_camera:| `Success is More Than Not Failing `__ Theories/Philosophy ------------------- - |:newspaper:| `What Is Technical Documentation? `__ -- |:movie_camera:| `Cognitive Ergonomics in Technical Writing - Lessons from the Field `__ -- |:movie_camera:| `7 Essential Tips for the Enlightened Tech Writer `__ -- |:movie_camera:| `Peanuts and Minimalism and Technical Writing `__ -- |:movie_camera:| `7 Values of Effective Tech Writing Teams `__ -- |:movie_camera:| `Poll the Docs `__ +- |:movie_camera:| `Cognitive Ergonomics in Technical Writing - Lessons from the Field `__ +- |:movie_camera:| `7 Essential Tips for the Enlightened Tech Writer `__ +- |:movie_camera:| `Peanuts and Minimalism and Technical Writing `__ +- |:movie_camera:| `7 Values of Effective Tech Writing Teams `__ +- |:movie_camera:| `Poll the Docs `__ Maths, science and history -------------------------- -- |:movie_camera:| `The Secret History of Libraries `__ -- |:movie_camera:| `A Journey to Pattern Languages `__ +- |:movie_camera:| `The Secret History of Libraries `__ +- |:movie_camera:| `A Journey to Pattern Languages `__ - |:movie_camera:| `Facebook, Dynamite, Uber, Bombs, and You `__ -- |:movie_camera:| `A brief history of text markup languages `__ -- |:movie_camera:| `Tech Writers Without Borders: Making the world a better place, one (numbered) step at a time `__ +- |:movie_camera:| `A brief history of text markup languages `__ +- |:movie_camera:| `Tech Writers Without Borders: Making the world a better place, one (numbered) step at a time `__ - |:movie_camera:| `Intelligent Documents and the Verifiability Crisis in Science `__ -- |:movie_camera:| `Accessible Math on the Web: A Server/Client Solution `__ -- |:movie_camera:| `The quest for scientific credit for software documentation `__ -- |:movie_camera:| `Back to the Future: What Can Documentarians Learn From The Past? `__ -- |:movie_camera:| `A brief history of math writing: symbol, structure, and proof `__ +- |:movie_camera:| `Accessible Math on the Web: A Server/Client Solution `__ +- |:movie_camera:| `The quest for scientific credit for software documentation `__ +- |:movie_camera:| `Back to the Future: What Can Documentarians Learn From The Past? `__ +- |:movie_camera:| `A brief history of math writing: symbol, structure, and proof `__ diff --git a/docs/videos/index.rst b/docs/videos/index.rst index feef6b16cc..98223cf8d0 100644 --- a/docs/videos/index.rst +++ b/docs/videos/index.rst @@ -1,13 +1,6 @@ Video Archive ============= -.. toctree:: - :glob: - :maxdepth: 1 +We no longer host the video archive on this site. - au/*/index - australia/*/index - eu/*/index - na/*/index - portland/*/index - prague/*/index +Watch all Write the Docs talks on our `YouTube channel `_.