From 58d7eb5bb89a56166193c679eb841c4c9f767b8a Mon Sep 17 00:00:00 2001 From: Jon Banafato Date: Mon, 29 Jul 2024 16:06:13 -0400 Subject: [PATCH 1/7] Write The Docs AU 2018: move talk abstracts into description field --- .../videos/backseat-content-strategy-laura-bailey.json | 3 +-- .../creating-experiences-with-information-daniel-stevens.json | 3 +-- .../facebook-dynamite-uber-bombs-and-you-lana-brindley.json | 3 +-- .../videos/good-code-bad-code-code-review-matthew-borden.json | 3 +-- ...making-yourself-redundant-on-day-one-alexandra-perkins.json | 3 +-- ...t-team-to-create-better-documentation-mathew-patterson.json | 3 +-- ...resenting-your-information-on-any-device-mike-hamilton.json | 3 +-- ...stency-creating-an-in-house-style-guide-kristine-sihto.json | 3 +-- .../videos/the-subtle-art-of-interrogation-nicola-nye.json | 3 +-- .../ux-writing-let-your-product-speak-abhay-chokshi.json | 3 +-- ...tatic-site-generators-what-why-and-how-jessica-parsons.json | 3 +-- 11 files changed, 11 insertions(+), 22 deletions(-) diff --git a/writethedocs-au-2018/videos/backseat-content-strategy-laura-bailey.json b/writethedocs-au-2018/videos/backseat-content-strategy-laura-bailey.json index c37d379fe..a5e9db8f7 100644 --- a/writethedocs-au-2018/videos/backseat-content-strategy-laura-bailey.json +++ b/writethedocs-au-2018/videos/backseat-content-strategy-laura-bailey.json @@ -1,7 +1,6 @@ { - "abstract": "Over the course of 2018 I planned and helped execute a complete, ongoing\nrewrite of about 1000 pages of documentation - changing the markup\nlanguage, the focus (feature to user story), and the structure (linear\nto modular) - without actually being in charge of strategy, scheduling,\ntooling, or content.\n\nThis talk charts the process and provides recommendations for others\nattempting to instigate massive change on multiple fronts.\n", "copyright_text": null, - "description": "Write the Docs Australia 2018", + "description": "Over the course of 2018 I planned and helped execute a complete, ongoing\nrewrite of about 1000 pages of documentation - changing the markup\nlanguage, the focus (feature to user story), and the structure (linear\nto modular) - without actually being in charge of strategy, scheduling,\ntooling, or content.\n\nThis talk charts the process and provides recommendations for others\nattempting to instigate massive change on multiple fronts.\n", "duration": 1438, "language": "eng", "recorded": "2018-11-15", diff --git a/writethedocs-au-2018/videos/creating-experiences-with-information-daniel-stevens.json b/writethedocs-au-2018/videos/creating-experiences-with-information-daniel-stevens.json index c55dedf85..bbcc8aab2 100644 --- a/writethedocs-au-2018/videos/creating-experiences-with-information-daniel-stevens.json +++ b/writethedocs-au-2018/videos/creating-experiences-with-information-daniel-stevens.json @@ -1,7 +1,6 @@ { - "abstract": "I\u2019ll walk through how my team and I create an information experience\nthat feels human, helpful, and how we know if it\u2019s successful. Part of\nthat experience bridges the information gap between the messages you\nreceive before you log into an Atlassian product and the messages you\nreceive in the form of:\n\n- Introductory states\n- Blank states\n- Directional and instructive text in the app\n- UI copy and it's connection to user expectations and perceptions\n- Documentation and how it supports different functional journeys\n\nWe\u2019ll cover how working ahead of time with our marketing, content, and\nbrand teams allows us to know and influence user expectations throughout\ntheir early journey. We\u2019ll also talk about how far we have yet to go.\n", "copyright_text": null, - "description": "Write the Docs Australia 2018", + "description": "I\u2019ll walk through how my team and I create an information experience\nthat feels human, helpful, and how we know if it\u2019s successful. Part of\nthat experience bridges the information gap between the messages you\nreceive before you log into an Atlassian product and the messages you\nreceive in the form of:\n\n- Introductory states\n- Blank states\n- Directional and instructive text in the app\n- UI copy and it's connection to user expectations and perceptions\n- Documentation and how it supports different functional journeys\n\nWe\u2019ll cover how working ahead of time with our marketing, content, and\nbrand teams allows us to know and influence user expectations throughout\ntheir early journey. We\u2019ll also talk about how far we have yet to go.\n", "duration": 1697, "language": "eng", "recorded": "2018-11-15", diff --git a/writethedocs-au-2018/videos/facebook-dynamite-uber-bombs-and-you-lana-brindley.json b/writethedocs-au-2018/videos/facebook-dynamite-uber-bombs-and-you-lana-brindley.json index 85c35206b..e1d4390ea 100644 --- a/writethedocs-au-2018/videos/facebook-dynamite-uber-bombs-and-you-lana-brindley.json +++ b/writethedocs-au-2018/videos/facebook-dynamite-uber-bombs-and-you-lana-brindley.json @@ -1,7 +1,6 @@ { - "abstract": "Most industries have had what we might call an oh-no moment. It's those\nmoments that encourage industries to become better regulated, in order\nto prevent further disasters. The IT industry has had many moments that\ncould be considered consequential enough to encourage better regulation,\nbut the changes have never been made. Because the industry has avoided\neffective regulation for so long, it is possible that we are hurtling\ntowards a disaster of epic proportions, one that we haven't even managed\nto conceive of yet.\n\nIn this talk, I will go through some historical examples of disasters\nleading to regulation in other industries, and the measures that were\nput into place to mitigate the problem. I will also address some of the\nmajor moments from the IT industry that should have prompted regulation,\nand haven't. Finally, I will discuss ways that documentation\nprofessionals are uniquely placed to identify, and potentially blow the\nwhistle on, potential disasters before they happen.\n", "copyright_text": null, - "description": "Write the Docs Australia 2018", + "description": "Most industries have had what we might call an oh-no moment. It's those\nmoments that encourage industries to become better regulated, in order\nto prevent further disasters. The IT industry has had many moments that\ncould be considered consequential enough to encourage better regulation,\nbut the changes have never been made. Because the industry has avoided\neffective regulation for so long, it is possible that we are hurtling\ntowards a disaster of epic proportions, one that we haven't even managed\nto conceive of yet.\n\nIn this talk, I will go through some historical examples of disasters\nleading to regulation in other industries, and the measures that were\nput into place to mitigate the problem. I will also address some of the\nmajor moments from the IT industry that should have prompted regulation,\nand haven't. Finally, I will discuss ways that documentation\nprofessionals are uniquely placed to identify, and potentially blow the\nwhistle on, potential disasters before they happen.\n", "duration": 1466, "language": "eng", "recorded": "2018-11-15", diff --git a/writethedocs-au-2018/videos/good-code-bad-code-code-review-matthew-borden.json b/writethedocs-au-2018/videos/good-code-bad-code-code-review-matthew-borden.json index 260a0aa3a..9de4c62b9 100644 --- a/writethedocs-au-2018/videos/good-code-bad-code-code-review-matthew-borden.json +++ b/writethedocs-au-2018/videos/good-code-bad-code-code-review-matthew-borden.json @@ -1,7 +1,6 @@ { - "abstract": "Code review is the duty of every developer in a team. We are the guards\nof the mystical \u201cgood\u201d code and defenders against evil technical debt.\nIt\u2019s universally agreed that it\u2019s easy to spot \u201cbad\u201d code and much\nharder to determine \u201cgood\u201d code.\n\nI\u2019m going to share some of my experiences working on a team producing a\nlarge amount of code every day, with few reviewers. We\u2019ll dive into\nlooking for smart architectural and design decisions, coherently\nunderstanding what problem the author intended to solve and\nunderstanding how they implemented a solution.\n\nI\u2019ll touch on automating away the most common issues within Code Review\nand pulling the technical brains out of your team mates into great\ndocumentation. Most importantly we\u2019ll talk about the human side of code\nreview and how to manage code review within large and small teams. Code\nreview helps our teams grow institutional knowledge and shared\nunderstanding of the systems we build together. A strong understanding\nof how to review code will help you to write better code and help you\nhelp your teammates to write better code.\n", "copyright_text": null, - "description": "Write the Docs Australia 2018", + "description": "Code review is the duty of every developer in a team. We are the guards\nof the mystical \u201cgood\u201d code and defenders against evil technical debt.\nIt\u2019s universally agreed that it\u2019s easy to spot \u201cbad\u201d code and much\nharder to determine \u201cgood\u201d code.\n\nI\u2019m going to share some of my experiences working on a team producing a\nlarge amount of code every day, with few reviewers. We\u2019ll dive into\nlooking for smart architectural and design decisions, coherently\nunderstanding what problem the author intended to solve and\nunderstanding how they implemented a solution.\n\nI\u2019ll touch on automating away the most common issues within Code Review\nand pulling the technical brains out of your team mates into great\ndocumentation. Most importantly we\u2019ll talk about the human side of code\nreview and how to manage code review within large and small teams. Code\nreview helps our teams grow institutional knowledge and shared\nunderstanding of the systems we build together. A strong understanding\nof how to review code will help you to write better code and help you\nhelp your teammates to write better code.\n", "duration": 1188, "language": "eng", "recorded": "2018-11-15", diff --git a/writethedocs-au-2018/videos/making-yourself-redundant-on-day-one-alexandra-perkins.json b/writethedocs-au-2018/videos/making-yourself-redundant-on-day-one-alexandra-perkins.json index 290fe2b84..c4f570b4e 100644 --- a/writethedocs-au-2018/videos/making-yourself-redundant-on-day-one-alexandra-perkins.json +++ b/writethedocs-au-2018/videos/making-yourself-redundant-on-day-one-alexandra-perkins.json @@ -1,7 +1,6 @@ { - "abstract": "The first few weeks at a new job are hard. There seem to be too many\nquestions and not enough answers, and so much assumed knowledge about\nthe company you joined and the products they make.\n\nI\u2019m going to talk about how you can make those first few weeks your most\nproductive and valuable to your new company. By writing internal\ndocumentation that answers all the questions only someone new on the\nblock knows to ask, you can help pave the way for new hires in the\nfuture, and even help identify and solve customer pain points.\n\nDrawing from my own experiences working as an intern and support agent\namong highly technical teams, I will go over deciding what to document\nbased on the level of technical proficiency you would expect the reader\nto have, how to use tone to convey the company\u2019s spirit and keep a\nfuture reader interested, and how to future-proof your internal\ndocumentation so it doesn\u2019t stop being updated when you move on.\n", "copyright_text": null, - "description": "This video is about internal docs to teach the next hire what you've learned.", + "description": "The first few weeks at a new job are hard. There seem to be too many\nquestions and not enough answers, and so much assumed knowledge about\nthe company you joined and the products they make.\n\nI\u2019m going to talk about how you can make those first few weeks your most\nproductive and valuable to your new company. By writing internal\ndocumentation that answers all the questions only someone new on the\nblock knows to ask, you can help pave the way for new hires in the\nfuture, and even help identify and solve customer pain points.\n\nDrawing from my own experiences working as an intern and support agent\namong highly technical teams, I will go over deciding what to document\nbased on the level of technical proficiency you would expect the reader\nto have, how to use tone to convey the company\u2019s spirit and keep a\nfuture reader interested, and how to future-proof your internal\ndocumentation so it doesn\u2019t stop being updated when you move on.\n", "duration": 1094, "language": "eng", "recorded": "2018-11-15", diff --git a/writethedocs-au-2018/videos/power-up-your-support-team-to-create-better-documentation-mathew-patterson.json b/writethedocs-au-2018/videos/power-up-your-support-team-to-create-better-documentation-mathew-patterson.json index 01c02c829..de0a0f1c0 100644 --- a/writethedocs-au-2018/videos/power-up-your-support-team-to-create-better-documentation-mathew-patterson.json +++ b/writethedocs-au-2018/videos/power-up-your-support-team-to-create-better-documentation-mathew-patterson.json @@ -1,7 +1,6 @@ { - "abstract": "Software support teams are in a tough spot. They know documentation is\nimportant, and they love to refer customers to it, but finding time to\nactually write and maintain those documents is *really* hard.\n\nThat endless support queue and its ceaseless demand for attention mean\nthat documentation is too often ignored. Mat shares his hard earned\npractical advice to help technical writers and support team knowledge\nbase owners create a more effective documentation system.\n\nLearn why documentation falls behind, how to reduce support writing\nfriction and how other SaaS teams have made support an engine for great\ndocumentation.\n", "copyright_text": null, - "description": "Write the Docs Australia 2018", + "description": "Software support teams are in a tough spot. They know documentation is\nimportant, and they love to refer customers to it, but finding time to\nactually write and maintain those documents is *really* hard.\n\nThat endless support queue and its ceaseless demand for attention mean\nthat documentation is too often ignored. Mat shares his hard earned\npractical advice to help technical writers and support team knowledge\nbase owners create a more effective documentation system.\n\nLearn why documentation falls behind, how to reduce support writing\nfriction and how other SaaS teams have made support an engine for great\ndocumentation.\n", "duration": 1585, "language": "eng", "recorded": "2018-11-15", diff --git a/writethedocs-au-2018/videos/responsive-content-presenting-your-information-on-any-device-mike-hamilton.json b/writethedocs-au-2018/videos/responsive-content-presenting-your-information-on-any-device-mike-hamilton.json index 1414c0f9d..69561defc 100644 --- a/writethedocs-au-2018/videos/responsive-content-presenting-your-information-on-any-device-mike-hamilton.json +++ b/writethedocs-au-2018/videos/responsive-content-presenting-your-information-on-any-device-mike-hamilton.json @@ -1,7 +1,6 @@ { - "abstract": "Creating high quality and engaging content is a challenge, but finding\nways to present that content to readers on a vast array of devices and\nhardware has been even more problematic. This session will explore best\npractices for enabling your content to automatically adapt to various\ncomputers, browsers, devices, and platforms. This is a rapidly changing\narea.\n\nIn this presentation Mike will cover the most recent developments in the\nindustry that have made responsive content presentation much easier for\ncontent authors. Mike will visit the concept of Media Queries and\ncompare that with the newer and easier techniques such as using the\nFlexBox Model. It has never been easier to ensure that your content is\npresented to your reader in an optimized manner.\n", "copyright_text": null, - "description": "Write the Docs Australia 2018", + "description": "Creating high quality and engaging content is a challenge, but finding\nways to present that content to readers on a vast array of devices and\nhardware has been even more problematic. This session will explore best\npractices for enabling your content to automatically adapt to various\ncomputers, browsers, devices, and platforms. This is a rapidly changing\narea.\n\nIn this presentation Mike will cover the most recent developments in the\nindustry that have made responsive content presentation much easier for\ncontent authors. Mike will visit the concept of Media Queries and\ncompare that with the newer and easier techniques such as using the\nFlexBox Model. It has never been easier to ensure that your content is\npresented to your reader in an optimized manner.\n", "duration": 1864, "language": "eng", "recorded": "2018-11-15", diff --git a/writethedocs-au-2018/videos/the-art-of-consistency-creating-an-in-house-style-guide-kristine-sihto.json b/writethedocs-au-2018/videos/the-art-of-consistency-creating-an-in-house-style-guide-kristine-sihto.json index f324c4fa9..249a91f33 100644 --- a/writethedocs-au-2018/videos/the-art-of-consistency-creating-an-in-house-style-guide-kristine-sihto.json +++ b/writethedocs-au-2018/videos/the-art-of-consistency-creating-an-in-house-style-guide-kristine-sihto.json @@ -1,7 +1,6 @@ { - "abstract": "For any business that\u2019s producing a lot of documentation from a lot of\nhands, a style guide is a necessity. It can provide consistent quality\nacross documents, and over time it can lift the writing standard within\nyour organisation.\n\nThis talk will aim to cover:\n\n- What does your style guide need to contain?\n- What are the pitfalls that you need to consider?\n- How do you communicate the style guide across the organisation?\n", "copyright_text": null, - "description": "Write the Docs Australia 2018", + "description": "For any business that\u2019s producing a lot of documentation from a lot of\nhands, a style guide is a necessity. It can provide consistent quality\nacross documents, and over time it can lift the writing standard within\nyour organisation.\n\nThis talk will aim to cover:\n\n- What does your style guide need to contain?\n- What are the pitfalls that you need to consider?\n- How do you communicate the style guide across the organisation?\n", "duration": 1558, "language": "eng", "recorded": "2018-11-15", diff --git a/writethedocs-au-2018/videos/the-subtle-art-of-interrogation-nicola-nye.json b/writethedocs-au-2018/videos/the-subtle-art-of-interrogation-nicola-nye.json index 69b3a152a..218b3518f 100644 --- a/writethedocs-au-2018/videos/the-subtle-art-of-interrogation-nicola-nye.json +++ b/writethedocs-au-2018/videos/the-subtle-art-of-interrogation-nicola-nye.json @@ -1,7 +1,6 @@ { - "abstract": "You have to write some docs. To do this, you need information from other\npeople.\n\nExcept that they're too busy, or in another office, or another timezone,\nor they just don't want to help. What do you do?\n\nThis talk will look at the psychology behind why we often don't get the\nhelp we ask for, how we can work with what we've got, and ways we can\nget information out of unwilling participants, in spite of themselves!\n", "copyright_text": null, - "description": "Write the Docs Australia 2018", + "description": "You have to write some docs. To do this, you need information from other\npeople.\n\nExcept that they're too busy, or in another office, or another timezone,\nor they just don't want to help. What do you do?\n\nThis talk will look at the psychology behind why we often don't get the\nhelp we ask for, how we can work with what we've got, and ways we can\nget information out of unwilling participants, in spite of themselves!\n", "duration": 1704, "language": "eng", "recorded": "2018-11-15", diff --git a/writethedocs-au-2018/videos/ux-writing-let-your-product-speak-abhay-chokshi.json b/writethedocs-au-2018/videos/ux-writing-let-your-product-speak-abhay-chokshi.json index 0f3a0ffa9..8a9739b05 100644 --- a/writethedocs-au-2018/videos/ux-writing-let-your-product-speak-abhay-chokshi.json +++ b/writethedocs-au-2018/videos/ux-writing-let-your-product-speak-abhay-chokshi.json @@ -1,7 +1,6 @@ { - "abstract": "The most common perception around the term UX writing is that it only\nincludes microcopy for the user interfaces. However, that is not\ncorrect. Writing snappy messages on the UI is only a part of it; more\nimportant aspect is developing a voice for the product and imbibing that\nvoice in your content (UX, help, knowledge base, etc).\n\nThis talk covers some of the necessary skills required for being good at\nUX writing and how these skills help us in designing a better product\nexperience. Whether be it the decision of keeping the tone professional\nvs casual or using title case vs sentence case, decisions must be taken\nbased on the audience and should always be in-context.\n\nAnd yea, one last thing, technical writers are/can be great UX writers!\n", "copyright_text": null, - "description": "Write the Docs Australia", + "description": "The most common perception around the term UX writing is that it only\nincludes microcopy for the user interfaces. However, that is not\ncorrect. Writing snappy messages on the UI is only a part of it; more\nimportant aspect is developing a voice for the product and imbibing that\nvoice in your content (UX, help, knowledge base, etc).\n\nThis talk covers some of the necessary skills required for being good at\nUX writing and how these skills help us in designing a better product\nexperience. Whether be it the decision of keeping the tone professional\nvs casual or using title case vs sentence case, decisions must be taken\nbased on the audience and should always be in-context.\n\nAnd yea, one last thing, technical writers are/can be great UX writers!\n", "duration": 1357, "language": "eng", "recorded": "2018-11-15", diff --git a/writethedocs-au-2018/videos/workshop-static-site-generators-what-why-and-how-jessica-parsons.json b/writethedocs-au-2018/videos/workshop-static-site-generators-what-why-and-how-jessica-parsons.json index b9799d112..7ae4433ce 100644 --- a/writethedocs-au-2018/videos/workshop-static-site-generators-what-why-and-how-jessica-parsons.json +++ b/writethedocs-au-2018/videos/workshop-static-site-generators-what-why-and-how-jessica-parsons.json @@ -1,7 +1,6 @@ { - "abstract": "As many documentation teams move towards a docs-as-code workflow, most\nare turning to static site generators like Jekyll, Sphynx, Hugo, or\nGitBook to turn that 'code' into user-facing documentation websites. In\nthis mini- workshop, you'll get an introduction to the static site\ngenerator landscape, and apply what you learn by publishing your own\nsite in class. We'll cover:\n\n- How static site generators work\n- Comparison of popular generators, with guidelines for choosing one\n for your next project\n- Hands-on editing and publishing of your own statically generated\n portfolio website\n", "copyright_text": null, - "description": "Write the Docs Australia 2018", + "description": "As many documentation teams move towards a docs-as-code workflow, most\nare turning to static site generators like Jekyll, Sphynx, Hugo, or\nGitBook to turn that 'code' into user-facing documentation websites. In\nthis mini- workshop, you'll get an introduction to the static site\ngenerator landscape, and apply what you learn by publishing your own\nsite in class. We'll cover:\n\n- How static site generators work\n- Comparison of popular generators, with guidelines for choosing one\n for your next project\n- Hands-on editing and publishing of your own statically generated\n portfolio website\n", "duration": 3479, "language": "eng", "recorded": "2018-11-15", From 2ed3cd5085c05c3a6c0678a10fdaaaa1775719db Mon Sep 17 00:00:00 2001 From: Jon Banafato Date: Mon, 29 Jul 2024 16:07:45 -0400 Subject: [PATCH 2/7] Write The Docs EU 2018: move talk abstracts into description field --- .../a-brief-history-of-text-markup-languages-tony-ibbs.json | 3 +-- ...year-in-the-life-of-the-better-docs-project-rowan-cota.json | 3 +-- .../videos/a11y-friendly-documentation-carolyn-stransky.json | 3 +-- .../choosing-a-tool-and-choosing-your-moment-val-grimm.json | 3 +-- ...t-practice-for-process-documentation-gillian-von-runte.json | 3 +-- writethedocs-eu-2018/videos/don-t-say-simply-jim-fisher.json | 3 +-- ...on-and-rewrite-docs-that-actually-work-alexandra-white.json | 3 +-- ...ing-known-issues-and-product-shortcomings-ivana-devcic.json | 3 +-- .../videos/learning-to-love-release-notes-anne-edwards.json | 3 +-- ...measuring-the-impact-of-your-documentation-liam-keegan.json | 3 +-- .../videos/run-your-documentation-predrag-mandic.json | 3 +-- .../videos/so-you-want-to-make-videos-sarah-ley-hamilton.json | 3 +-- .../tackling-technical-debt-in-the-docs-louise-fahey.json | 3 +-- ...tales-of-a-contagious-documentarian-abigail-sutherland.json | 3 +-- .../videos/what-about-compliance-vlad-stirbu.json | 3 +-- 15 files changed, 15 insertions(+), 30 deletions(-) diff --git a/writethedocs-eu-2018/videos/a-brief-history-of-text-markup-languages-tony-ibbs.json b/writethedocs-eu-2018/videos/a-brief-history-of-text-markup-languages-tony-ibbs.json index 653703d0d..6036a7ef4 100644 --- a/writethedocs-eu-2018/videos/a-brief-history-of-text-markup-languages-tony-ibbs.json +++ b/writethedocs-eu-2018/videos/a-brief-history-of-text-markup-languages-tony-ibbs.json @@ -1,7 +1,6 @@ { - "abstract": "There\u2019s a long history to text markup languages, and I don\u2019t think most\npeople know much of it. This talk gives a quick overview of the major\nformats, including nroff/troff, SGML, HTML, Docbook, TeX and LaTeX,\nsetext, reStructuredText, markdown and AsciiDoc.\n\nIn passing, I shall complain briefly about the history of wiki markups,\nand explain my reservations about markdown, and why it\u2019s still a good\nthing.\n\nThe slides, and extended notes, will be available at\nhttps://github.com/tibs/markup-history.\n", "copyright_text": null, - "description": "", + "description": "There\u2019s a long history to text markup languages, and I don\u2019t think most\npeople know much of it. This talk gives a quick overview of the major\nformats, including nroff/troff, SGML, HTML, Docbook, TeX and LaTeX,\nsetext, reStructuredText, markdown and AsciiDoc.\n\nIn passing, I shall complain briefly about the history of wiki markups,\nand explain my reservations about markdown, and why it\u2019s still a good\nthing.\n\nThe slides, and extended notes, will be available at\nhttps://github.com/tibs/markup-history.\n", "duration": 1827, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/a-year-in-the-life-of-the-better-docs-project-rowan-cota.json b/writethedocs-eu-2018/videos/a-year-in-the-life-of-the-better-docs-project-rowan-cota.json index 3a31c5c45..5b86d7021 100644 --- a/writethedocs-eu-2018/videos/a-year-in-the-life-of-the-better-docs-project-rowan-cota.json +++ b/writethedocs-eu-2018/videos/a-year-in-the-life-of-the-better-docs-project-rowan-cota.json @@ -1,7 +1,6 @@ { - "abstract": "A year ago (or so) BuzzFeed realized we had a documentation problem. Our\ndocs were kept in numerous places, from Google Drive to Wikis to Github\nfolders to...places we may not even have found yet! In response we\nstarted a working group called The Better Docs Project, with the mission\nof organizing, standardizing, and completing our documentation.\n\nDuring this talk we\u2019ll go on a narrative journey through the first year\nof Better Docs, talking about what worked for us, what didn\u2019t work, what\nwe\u2019re excited to try next, and the lessons we\u2019ve learned (and friends\nwe\u2019ve made) along the way. I\u2019ll share actionable tips for how to steal\nour experience to get your own projects and workplaces on the road to\nBetter Docs.\n", "copyright_text": null, - "description": "", + "description": "A year ago (or so) BuzzFeed realized we had a documentation problem. Our\ndocs were kept in numerous places, from Google Drive to Wikis to Github\nfolders to...places we may not even have found yet! In response we\nstarted a working group called The Better Docs Project, with the mission\nof organizing, standardizing, and completing our documentation.\n\nDuring this talk we\u2019ll go on a narrative journey through the first year\nof Better Docs, talking about what worked for us, what didn\u2019t work, what\nwe\u2019re excited to try next, and the lessons we\u2019ve learned (and friends\nwe\u2019ve made) along the way. I\u2019ll share actionable tips for how to steal\nour experience to get your own projects and workplaces on the road to\nBetter Docs.\n", "duration": 1801, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/a11y-friendly-documentation-carolyn-stransky.json b/writethedocs-eu-2018/videos/a11y-friendly-documentation-carolyn-stransky.json index 1d4081c60..ea81a9475 100644 --- a/writethedocs-eu-2018/videos/a11y-friendly-documentation-carolyn-stransky.json +++ b/writethedocs-eu-2018/videos/a11y-friendly-documentation-carolyn-stransky.json @@ -1,7 +1,6 @@ { - "abstract": "Accessibility (a11y) has been finding its stride in the web development\ncommunity \u2010 and it\u2019s not hard to figure out why. According to the World\nHealth Organization, there are over one billion people globally who need\nan assistive device. With these statistics, organizations and open\nsource projects alike realize that they could be unintentionally locking\nthese people out of their products. As a result, they adjust their\ndeveloper workflows. And it often ends there, at the product.\nDocumentation is left out of the conversation.\n\nIf documentation is meant to serve as a tool for learning and\ncomprehension, then it must be included in those conversations. After\nall, we want to write docs that are truly for everyone \u2010 regardless of\nthe technology they use to read it.\n\nIn this talk, we\u2019ll look at how assistive technology consumes\ndocumentation and cover some points to consider when building out your\ndocs. Along the way, we\u2019ll touch on quick regulation wins and inclusive\nwriting practices.\n", "copyright_text": null, - "description": "", + "description": "Accessibility (a11y) has been finding its stride in the web development\ncommunity \u2010 and it\u2019s not hard to figure out why. According to the World\nHealth Organization, there are over one billion people globally who need\nan assistive device. With these statistics, organizations and open\nsource projects alike realize that they could be unintentionally locking\nthese people out of their products. As a result, they adjust their\ndeveloper workflows. And it often ends there, at the product.\nDocumentation is left out of the conversation.\n\nIf documentation is meant to serve as a tool for learning and\ncomprehension, then it must be included in those conversations. After\nall, we want to write docs that are truly for everyone \u2010 regardless of\nthe technology they use to read it.\n\nIn this talk, we\u2019ll look at how assistive technology consumes\ndocumentation and cover some points to consider when building out your\ndocs. Along the way, we\u2019ll touch on quick regulation wins and inclusive\nwriting practices.\n", "duration": 1757, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/choosing-a-tool-and-choosing-your-moment-val-grimm.json b/writethedocs-eu-2018/videos/choosing-a-tool-and-choosing-your-moment-val-grimm.json index 0b15597e4..6db55653f 100644 --- a/writethedocs-eu-2018/videos/choosing-a-tool-and-choosing-your-moment-val-grimm.json +++ b/writethedocs-eu-2018/videos/choosing-a-tool-and-choosing-your-moment-val-grimm.json @@ -1,7 +1,6 @@ { - "abstract": "When you're suffering with an inadequate toolset, especially if you've\njust come back from a conference, you may feel like \"Now is the time for\nchange!\". However, your first step should be analysis. Before you can\ndecide this is the right moment for a new tool, let alone choose a tool,\nyou need to assess your organization's needs and current status. Your\ndecision should be defined by a triangle of factors: bigger picture\nstrategic goals, operational reality, related processes, and existing\nsystems. But when it isn't the right time, it is still possible to make\nprogress with continued assessment and incremental change...\n", "copyright_text": null, - "description": "", + "description": "When you're suffering with an inadequate toolset, especially if you've\njust come back from a conference, you may feel like \"Now is the time for\nchange!\". However, your first step should be analysis. Before you can\ndecide this is the right moment for a new tool, let alone choose a tool,\nyou need to assess your organization's needs and current status. Your\ndecision should be defined by a triangle of factors: bigger picture\nstrategic goals, operational reality, related processes, and existing\nsystems. But when it isn't the right time, it is still possible to make\nprogress with continued assessment and incremental change...\n", "duration": 1396, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/document-what-matters-lean-best-practice-for-process-documentation-gillian-von-runte.json b/writethedocs-eu-2018/videos/document-what-matters-lean-best-practice-for-process-documentation-gillian-von-runte.json index 996ea58a7..1f0e422cd 100644 --- a/writethedocs-eu-2018/videos/document-what-matters-lean-best-practice-for-process-documentation-gillian-von-runte.json +++ b/writethedocs-eu-2018/videos/document-what-matters-lean-best-practice-for-process-documentation-gillian-von-runte.json @@ -1,7 +1,6 @@ { - "abstract": "As a Lean Trainer and Manager in service industries, I work with all\nkinds of teams to help them use process mapping to document their\nprocesses. Sifting through binders of documentation, pages of\nscreenshots, and step\u2010by\u2010step explanations can be time consuming and\nawkward, and large quantities of documentation are time consuming to\nkeep up to date. System updates would quickly render screenshots\nobsolete, and teams were quickly getting overwhelmed, giving up on\ndocumentation entirely. I started to apply my lean expertise to the art\nof process mapping, putting together a best practice toolkit to maintain\na minimalist approach to documenting processes.\n\nWe'll discuss best practice in process mapping for:\n\n- visual instruction in user guides and how\u2010to\u2019s\n- mapping process at high levels, avoiding getting bogged down in\n detail\n- assessing possible failure points to anticipate customer pain points\n (to manage through customer documentation)\n", "copyright_text": null, - "description": "", + "description": "As a Lean Trainer and Manager in service industries, I work with all\nkinds of teams to help them use process mapping to document their\nprocesses. Sifting through binders of documentation, pages of\nscreenshots, and step\u2010by\u2010step explanations can be time consuming and\nawkward, and large quantities of documentation are time consuming to\nkeep up to date. System updates would quickly render screenshots\nobsolete, and teams were quickly getting overwhelmed, giving up on\ndocumentation entirely. I started to apply my lean expertise to the art\nof process mapping, putting together a best practice toolkit to maintain\na minimalist approach to documenting processes.\n\nWe'll discuss best practice in process mapping for:\n\n- visual instruction in user guides and how\u2010to\u2019s\n- mapping process at high levels, avoiding getting bogged down in\n detail\n- assessing possible failure points to anticipate customer pain points\n (to manage through customer documentation)\n", "duration": 1491, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/don-t-say-simply-jim-fisher.json b/writethedocs-eu-2018/videos/don-t-say-simply-jim-fisher.json index 8193739f1..401b56201 100644 --- a/writethedocs-eu-2018/videos/don-t-say-simply-jim-fisher.json +++ b/writethedocs-eu-2018/videos/don-t-say-simply-jim-fisher.json @@ -1,7 +1,6 @@ { - "abstract": "To install, simply do [these several steps]! If you\u2019re like me, you\u2019ve\nwritten lots of documentation like this. We all want our products to be\nsimple. Worse, lots of us believe our products are simple. But trust me,\nthey\u2019re not simple! Your installation guide failed on step 2, and I\ndon\u2019t know how to fix it! In this talk I highlight some writing styles\nwhich seem innocuous when written, but which show a lack of sympathy\nwhen read. I suggest some ways to avoid these pitfalls and bridge the\ngap with your reader.\n", "copyright_text": null, - "description": "", + "description": "To install, simply do [these several steps]! If you\u2019re like me, you\u2019ve\nwritten lots of documentation like this. We all want our products to be\nsimple. Worse, lots of us believe our products are simple. But trust me,\nthey\u2019re not simple! Your installation guide failed on step 2, and I\ndon\u2019t know how to fix it! In this talk I highlight some writing styles\nwhich seem innocuous when written, but which show a lack of sympathy\nwhen read. I suggest some ways to avoid these pitfalls and bridge the\ngap with your reader.\n", "duration": 1818, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/how-to-tear-down-existing-documentation-and-rewrite-docs-that-actually-work-alexandra-white.json b/writethedocs-eu-2018/videos/how-to-tear-down-existing-documentation-and-rewrite-docs-that-actually-work-alexandra-white.json index 4808f9793..a072e5e17 100644 --- a/writethedocs-eu-2018/videos/how-to-tear-down-existing-documentation-and-rewrite-docs-that-actually-work-alexandra-white.json +++ b/writethedocs-eu-2018/videos/how-to-tear-down-existing-documentation-and-rewrite-docs-that-actually-work-alexandra-white.json @@ -1,7 +1,6 @@ { - "abstract": "We all know what it\u2019s like to look at a series of existing documentation\nand think, \u201chow did this happen?\u201d Be it a large swath of unorganized\ncontent or a lack of a clear strategy, the complications of bad docs\naren\u2019t just a curse for documentation editors. Our readers see it, too.\nIt leads to confused support requests and possibly a loss of customers.\n\nWhen I started at Joyent, I was continuously made aware of documentation\nthat needed help, and it felt like a nonstop firefight. Over time, I was\nable to quell the fires, create a content strategy, and completely\nredefine how our documentation works. Then all of my work was blown up a\nsecond time \u2010 this time, starting from scratch with a not yet existing\nproduct. From this experience, I\u2019ve learned it\u2019s all about being\norganized and having a clear strategy.\n\nIn this talk, we\u2019ll discuss:\n\n- how to get buy\u2010in for a documentation do\u2010over\n- how to pivot from rewriting docs to starting from scratch\n- content strategy (and how to write a great one)\n- empathy for our readers\n- setting easy\u2010to\u2010follow guidelines for non\u2010professional writers\n\nWe\u2019ll also touch on how to prioritize and manage all of this work\nwithout additional full\u2010time documentation help.\n", "copyright_text": null, - "description": "", + "description": "We all know what it\u2019s like to look at a series of existing documentation\nand think, \u201chow did this happen?\u201d Be it a large swath of unorganized\ncontent or a lack of a clear strategy, the complications of bad docs\naren\u2019t just a curse for documentation editors. Our readers see it, too.\nIt leads to confused support requests and possibly a loss of customers.\n\nWhen I started at Joyent, I was continuously made aware of documentation\nthat needed help, and it felt like a nonstop firefight. Over time, I was\nable to quell the fires, create a content strategy, and completely\nredefine how our documentation works. Then all of my work was blown up a\nsecond time \u2010 this time, starting from scratch with a not yet existing\nproduct. From this experience, I\u2019ve learned it\u2019s all about being\norganized and having a clear strategy.\n\nIn this talk, we\u2019ll discuss:\n\n- how to get buy\u2010in for a documentation do\u2010over\n- how to pivot from rewriting docs to starting from scratch\n- content strategy (and how to write a great one)\n- empathy for our readers\n- setting easy\u2010to\u2010follow guidelines for non\u2010professional writers\n\nWe\u2019ll also touch on how to prioritize and manage all of this work\nwithout additional full\u2010time documentation help.\n", "duration": 1594, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/it-s-a-feature-documenting-known-issues-and-product-shortcomings-ivana-devcic.json b/writethedocs-eu-2018/videos/it-s-a-feature-documenting-known-issues-and-product-shortcomings-ivana-devcic.json index 8824ab280..821825508 100644 --- a/writethedocs-eu-2018/videos/it-s-a-feature-documenting-known-issues-and-product-shortcomings-ivana-devcic.json +++ b/writethedocs-eu-2018/videos/it-s-a-feature-documenting-known-issues-and-product-shortcomings-ivana-devcic.json @@ -1,7 +1,6 @@ { - "abstract": "Imagine for a moment that documentation is the face of your product. How\nmuch concealer would you put on it?\n\nThe majority of people would likely agree that no product is ever\nperfect. When it comes to software, the jokes about bugs practically\nwrite themselves. Should the product documentation acknowledge this, or\nshould it cover up the imperfections? In some cases, the answer seems\nobvious, but what about those situations where there is a major known\nissue - or five? How should the person in charge of documentation\naddress this? Should they just stick a big warning into the release\nnotes, or point out the problem and offer a quick workaround in the\ndocumentation itself?\n\nThis is not only a content issue, but also a question of ethics. It is a\nchallenge that has come up time and again in my personal (albeit short)\ncareer as a technical writer, and I suspect many others have faced it,\ntoo.\n\nThis talk will look at some strategies that writers can rely on if they\ndecide this is an issue worth considering. Important aspects that will\nbe covered include:\n\n- the tone and language used when addressing product shortcomings\n- communication with stakeholders, product managers and other\n subject-matter experts\n- dealing with clunky or unintuitive UIs and workflows that are not\n officially recognized as issues, but are still impeding the user\n experience and understanding of the product\n", "copyright_text": null, - "description": "", + "description": "Imagine for a moment that documentation is the face of your product. How\nmuch concealer would you put on it?\n\nThe majority of people would likely agree that no product is ever\nperfect. When it comes to software, the jokes about bugs practically\nwrite themselves. Should the product documentation acknowledge this, or\nshould it cover up the imperfections? In some cases, the answer seems\nobvious, but what about those situations where there is a major known\nissue - or five? How should the person in charge of documentation\naddress this? Should they just stick a big warning into the release\nnotes, or point out the problem and offer a quick workaround in the\ndocumentation itself?\n\nThis is not only a content issue, but also a question of ethics. It is a\nchallenge that has come up time and again in my personal (albeit short)\ncareer as a technical writer, and I suspect many others have faced it,\ntoo.\n\nThis talk will look at some strategies that writers can rely on if they\ndecide this is an issue worth considering. Important aspects that will\nbe covered include:\n\n- the tone and language used when addressing product shortcomings\n- communication with stakeholders, product managers and other\n subject-matter experts\n- dealing with clunky or unintuitive UIs and workflows that are not\n officially recognized as issues, but are still impeding the user\n experience and understanding of the product\n", "duration": 952, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/learning-to-love-release-notes-anne-edwards.json b/writethedocs-eu-2018/videos/learning-to-love-release-notes-anne-edwards.json index 366c60047..798e4458d 100644 --- a/writethedocs-eu-2018/videos/learning-to-love-release-notes-anne-edwards.json +++ b/writethedocs-eu-2018/videos/learning-to-love-release-notes-anne-edwards.json @@ -1,7 +1,6 @@ { - "abstract": "I\u2019ll be talking about an area of technical writing that\u2019s not\nparticularly glamorous, and tends not to get much love: the humble\nrelease note.\n\nWhen I joined my current company back in September 2017, I noticed we\ndidn\u2019t have a consistent format for our release notes, and they were\noften clunky and difficult to understand. And when I did a bit of\nresearch to see if there were any generally accepted formats, I was\nsurprised at how little guidance I found.\n\nI realised I had plenty of my own ideas about what made a good release\nnote (from reading and writing many over the years), so I gathered them\ntogether and gradually formed them into a style guide. Drawing from\nthis, I\u2019ll talk about:\n\n- making release notes easier to write \u2010 and read \u2010 by grouping them\n into categories and then using templates to write them\n- how you can improve readability with a few simple style tweaks\n- viewing release notes as a ready\u2010made opportunity to show your users\n the hard work you\u2019ve put into your product \u2010 the bugs you\u2019ve fixed,\n and the suggestions you\u2019ve listened to\n", "copyright_text": null, - "description": "", + "description": "I\u2019ll be talking about an area of technical writing that\u2019s not\nparticularly glamorous, and tends not to get much love: the humble\nrelease note.\n\nWhen I joined my current company back in September 2017, I noticed we\ndidn\u2019t have a consistent format for our release notes, and they were\noften clunky and difficult to understand. And when I did a bit of\nresearch to see if there were any generally accepted formats, I was\nsurprised at how little guidance I found.\n\nI realised I had plenty of my own ideas about what made a good release\nnote (from reading and writing many over the years), so I gathered them\ntogether and gradually formed them into a style guide. Drawing from\nthis, I\u2019ll talk about:\n\n- making release notes easier to write \u2010 and read \u2010 by grouping them\n into categories and then using templates to write them\n- how you can improve readability with a few simple style tweaks\n- viewing release notes as a ready\u2010made opportunity to show your users\n the hard work you\u2019ve put into your product \u2010 the bugs you\u2019ve fixed,\n and the suggestions you\u2019ve listened to\n", "duration": 1356, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/measuring-the-impact-of-your-documentation-liam-keegan.json b/writethedocs-eu-2018/videos/measuring-the-impact-of-your-documentation-liam-keegan.json index 24aa75b88..8a7858660 100644 --- a/writethedocs-eu-2018/videos/measuring-the-impact-of-your-documentation-liam-keegan.json +++ b/writethedocs-eu-2018/videos/measuring-the-impact-of-your-documentation-liam-keegan.json @@ -1,7 +1,6 @@ { - "abstract": "How do you prove that docs are key to growing a software business?\n\nDocumentarians have long struggled to get buy-in from stakeholders and\nwin more budget because the impact of docs on a company\u2019s bottom line\nhas never been clear.\n\nThings like traffic analysis, at best, tell you whether customers are\nfacing a recurring problem, or if they\u2019re finding your docs easily.\nArticle ratings also help you understand if customers find your docs\nuseful. But to prove that docs actually impact your bottom line, you\nneed to dig deeper.\n\nIn this talk, I\u2019ll share new models I\u2019ve designed to help measure if\nyour docs drive customer growth:\n\n- What would your company look like without docs? (A basic control for\n measuring success)\n- Do your docs help win new users? (Acquisition-focused attribution)\n- Are users who read your docs more likely to take the key steps to\n become customers? (Activation-focused attribution)\n- Can docs help convert new customers into loyal advocates?\n (Retention-focused attribution)\n\nI\u2019ll demonstrate how you can apply these models to your business, with\nboth theoretical and practical advice.\n", "copyright_text": null, - "description": "", + "description": "How do you prove that docs are key to growing a software business?\n\nDocumentarians have long struggled to get buy-in from stakeholders and\nwin more budget because the impact of docs on a company\u2019s bottom line\nhas never been clear.\n\nThings like traffic analysis, at best, tell you whether customers are\nfacing a recurring problem, or if they\u2019re finding your docs easily.\nArticle ratings also help you understand if customers find your docs\nuseful. But to prove that docs actually impact your bottom line, you\nneed to dig deeper.\n\nIn this talk, I\u2019ll share new models I\u2019ve designed to help measure if\nyour docs drive customer growth:\n\n- What would your company look like without docs? (A basic control for\n measuring success)\n- Do your docs help win new users? (Acquisition-focused attribution)\n- Are users who read your docs more likely to take the key steps to\n become customers? (Activation-focused attribution)\n- Can docs help convert new customers into loyal advocates?\n (Retention-focused attribution)\n\nI\u2019ll demonstrate how you can apply these models to your business, with\nboth theoretical and practical advice.\n", "duration": 1214, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/run-your-documentation-predrag-mandic.json b/writethedocs-eu-2018/videos/run-your-documentation-predrag-mandic.json index 18ea7d713..9125abce6 100644 --- a/writethedocs-eu-2018/videos/run-your-documentation-predrag-mandic.json +++ b/writethedocs-eu-2018/videos/run-your-documentation-predrag-mandic.json @@ -1,7 +1,6 @@ { - "abstract": "The journey, benefits and shortcomings of writing runnable\ndocumentation. A story behind the \"documentation is code\" principle and\nhow it saves money and time, empowers documentarians, simplifies\nprocesses around testing documentation and brings happiness to a diverse\ncustomer base.\n", "copyright_text": null, - "description": "", + "description": "The journey, benefits and shortcomings of writing runnable\ndocumentation. A story behind the \"documentation is code\" principle and\nhow it saves money and time, empowers documentarians, simplifies\nprocesses around testing documentation and brings happiness to a diverse\ncustomer base.\n", "duration": 1480, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/so-you-want-to-make-videos-sarah-ley-hamilton.json b/writethedocs-eu-2018/videos/so-you-want-to-make-videos-sarah-ley-hamilton.json index 9362955bb..5b05e6c3f 100644 --- a/writethedocs-eu-2018/videos/so-you-want-to-make-videos-sarah-ley-hamilton.json +++ b/writethedocs-eu-2018/videos/so-you-want-to-make-videos-sarah-ley-hamilton.json @@ -1,7 +1,6 @@ { - "abstract": "I started my career in technology, working in Customer Support for a\nsmall start up in little old New Zealand. To help our Support team scale\nas the business quickly grew, we needed to invest in a fool-proof\nself-service strategy.\n\nWe work in an industry with customers that don't identify themselves as\n\"tech savvy\", so to help them get up and running with our product\nquickly we needed friendly, accessible and engaging product education.\n\nVideo was one of the first things we identified as being a crucial part\nof our product education strategy. In this talk, I'll share my\nexperience with using, producing and managing videos, as part of\ndocumenting an ever-changing and evolving product. We\u2019ll chat about:\n\n- Why you should be making videos\n- When to use videos\n- When you shouldn't be making videos\n- How to develop a video strategy\n- How to make great product tutorials\n\nIf you're looking to start your adventure in video, this talk will give\nyou insight into how to develop and deliver a video strategy, with some\nhelpful insights and lessons learned along the way.\n", "copyright_text": null, - "description": "", + "description": "I started my career in technology, working in Customer Support for a\nsmall start up in little old New Zealand. To help our Support team scale\nas the business quickly grew, we needed to invest in a fool-proof\nself-service strategy.\n\nWe work in an industry with customers that don't identify themselves as\n\"tech savvy\", so to help them get up and running with our product\nquickly we needed friendly, accessible and engaging product education.\n\nVideo was one of the first things we identified as being a crucial part\nof our product education strategy. In this talk, I'll share my\nexperience with using, producing and managing videos, as part of\ndocumenting an ever-changing and evolving product. We\u2019ll chat about:\n\n- Why you should be making videos\n- When to use videos\n- When you shouldn't be making videos\n- How to develop a video strategy\n- How to make great product tutorials\n\nIf you're looking to start your adventure in video, this talk will give\nyou insight into how to develop and deliver a video strategy, with some\nhelpful insights and lessons learned along the way.\n", "duration": 1595, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/tackling-technical-debt-in-the-docs-louise-fahey.json b/writethedocs-eu-2018/videos/tackling-technical-debt-in-the-docs-louise-fahey.json index c62adcc5b..0b32d5cee 100644 --- a/writethedocs-eu-2018/videos/tackling-technical-debt-in-the-docs-louise-fahey.json +++ b/writethedocs-eu-2018/videos/tackling-technical-debt-in-the-docs-louise-fahey.json @@ -1,7 +1,6 @@ { - "abstract": "In a world of legacy content, how do we resolve the issue of technical\ndebt in our documentation?\n\nAs technical communicators, it\u2019s very easy to get caught up in the cycle\nof moving from one release to another without taking time to refine what\nalready exists. Trying to keep up with documenting new features means we\noften find ourselves navigating though outdated and disused\nstylesheets/labels/files/content/junk in projects that we inherited from\ntechnical communicators before us and haven\u2019t had the time to clean up.\n\nIf this sounds familiar, then this presentation is for you!\n\nIt aims to help you tackle the daunting task of cleaning up your project\nand getting rid of technical debt once and for all. We will cover:\n\n- What is technical debt, how does it accrue, and why should your\n organisation care\n- How you can tackle your debt and give your documentation project the\n spring clean it needs\n- Tips for staying debt\u2010free\n", "copyright_text": null, - "description": "", + "description": "In a world of legacy content, how do we resolve the issue of technical\ndebt in our documentation?\n\nAs technical communicators, it\u2019s very easy to get caught up in the cycle\nof moving from one release to another without taking time to refine what\nalready exists. Trying to keep up with documenting new features means we\noften find ourselves navigating though outdated and disused\nstylesheets/labels/files/content/junk in projects that we inherited from\ntechnical communicators before us and haven\u2019t had the time to clean up.\n\nIf this sounds familiar, then this presentation is for you!\n\nIt aims to help you tackle the daunting task of cleaning up your project\nand getting rid of technical debt once and for all. We will cover:\n\n- What is technical debt, how does it accrue, and why should your\n organisation care\n- How you can tackle your debt and give your documentation project the\n spring clean it needs\n- Tips for staying debt\u2010free\n", "duration": 1684, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/teaching-geeks-to-fish-tales-of-a-contagious-documentarian-abigail-sutherland.json b/writethedocs-eu-2018/videos/teaching-geeks-to-fish-tales-of-a-contagious-documentarian-abigail-sutherland.json index 663664941..33cce789e 100644 --- a/writethedocs-eu-2018/videos/teaching-geeks-to-fish-tales-of-a-contagious-documentarian-abigail-sutherland.json +++ b/writethedocs-eu-2018/videos/teaching-geeks-to-fish-tales-of-a-contagious-documentarian-abigail-sutherland.json @@ -1,7 +1,6 @@ { - "abstract": "I love my job. My title is \"Information Architect\", but that\u2019s mostly\nbecause \"She Who Figures Out What We Need To Do About Our Documentation\nAnd Does It\" is too wordy for HR. I work in a product unit of about 350\npeople creating software for developers, very few of them skilled\nwriters or native speakers of English. My role is to figure out how we\ncan produce good documentation.\n\nI have a problem of scale: I can\u2019t do all of the technical writing we\nneed. So instead, I\u2019ve become a contagious documentarian. Over the last\nyear, I\u2019ve [STRIKEOUT:infected] taught technical writing to over 200\npeople around my company. My 3 1/2 hour course, \"Technical Writing for\nTechies\", is popular, and seems to be effective. There\u2019s been a\nnoticeable improvement in the writing we\u2019re producing, and (even better)\nan awareness that good writing is an achievable, even enjoyable, thing.\n\nWhen I describe the course formally, I tend to list attendee objectives\nsuch as:\n\n- Think about the audience and how to write for them.\n- Study and practice different writing techniques.\n- Understand and use a style guide.\n- Learn ways to improve word choice and sentence structure.\n- Study the commonest mistakes that non\u2010native speakers make in English\n and how to correct them. (etc)\n\nAnd I do cover all of those topics. But just between us, my real\nobjectives for my students are:\n\n- Stay awake.\n- Feel welcome and relaxed enough to participate openly.\n- Finish the course feeling competent and capable about writing.\n- Trust the Information Architect enough to come to her with future\n problems.\n- Want to be part of a community of documentarians.\n\nI\u2019ll talk about the course structure, some of the ways I\u2019ve designed and\ndelivered it to meet both sets of objectives, how it has evolved over\ntime, and what I\u2019ve learned while giving it.\n", "copyright_text": null, - "description": "", + "description": "I love my job. My title is \"Information Architect\", but that\u2019s mostly\nbecause \"She Who Figures Out What We Need To Do About Our Documentation\nAnd Does It\" is too wordy for HR. I work in a product unit of about 350\npeople creating software for developers, very few of them skilled\nwriters or native speakers of English. My role is to figure out how we\ncan produce good documentation.\n\nI have a problem of scale: I can\u2019t do all of the technical writing we\nneed. So instead, I\u2019ve become a contagious documentarian. Over the last\nyear, I\u2019ve [STRIKEOUT:infected] taught technical writing to over 200\npeople around my company. My 3 1/2 hour course, \"Technical Writing for\nTechies\", is popular, and seems to be effective. There\u2019s been a\nnoticeable improvement in the writing we\u2019re producing, and (even better)\nan awareness that good writing is an achievable, even enjoyable, thing.\n\nWhen I describe the course formally, I tend to list attendee objectives\nsuch as:\n\n- Think about the audience and how to write for them.\n- Study and practice different writing techniques.\n- Understand and use a style guide.\n- Learn ways to improve word choice and sentence structure.\n- Study the commonest mistakes that non\u2010native speakers make in English\n and how to correct them. (etc)\n\nAnd I do cover all of those topics. But just between us, my real\nobjectives for my students are:\n\n- Stay awake.\n- Feel welcome and relaxed enough to participate openly.\n- Finish the course feeling competent and capable about writing.\n- Trust the Information Architect enough to come to her with future\n problems.\n- Want to be part of a community of documentarians.\n\nI\u2019ll talk about the course structure, some of the ways I\u2019ve designed and\ndelivered it to meet both sets of objectives, how it has evolved over\ntime, and what I\u2019ve learned while giving it.\n", "duration": 1559, "language": "eng", "recorded": "2018-09-10", diff --git a/writethedocs-eu-2018/videos/what-about-compliance-vlad-stirbu.json b/writethedocs-eu-2018/videos/what-about-compliance-vlad-stirbu.json index d42fa4cab..164592eb2 100644 --- a/writethedocs-eu-2018/videos/what-about-compliance-vlad-stirbu.json +++ b/writethedocs-eu-2018/videos/what-about-compliance-vlad-stirbu.json @@ -1,7 +1,6 @@ { - "abstract": "My team developed software that was used as part of a medical product.\nWe used modern development practices and tools to document the code and\nthe APIs exposed by our microservices, but was that enough?\n\nThis talk introduces the audience to the particularities of developing\nmedical device software and the regulatory landscape that you must\ncomply with. I\u2019ll focus specifically on the processes and culture that\nenables the creation of medical software device documentation intended\nfor auditors, without damaging (too much) the team velocity and spirit.\n", "copyright_text": null, - "description": "", + "description": "My team developed software that was used as part of a medical product.\nWe used modern development practices and tools to document the code and\nthe APIs exposed by our microservices, but was that enough?\n\nThis talk introduces the audience to the particularities of developing\nmedical device software and the regulatory landscape that you must\ncomply with. I\u2019ll focus specifically on the processes and culture that\nenables the creation of medical software device documentation intended\nfor auditors, without damaging (too much) the team velocity and spirit.\n", "duration": 1823, "language": "eng", "recorded": "2018-09-10", From a82d8da4580d0adec229a69e2a19bf2d2900082a Mon Sep 17 00:00:00 2001 From: Jon Banafato Date: Mon, 29 Jul 2024 16:08:38 -0400 Subject: [PATCH 3/7] Write The Docs NA 2018: move talk abstracts into description field --- ...ned-tech-writer-ted-hudek-write-the-docs-portland-2018.json | 3 +-- ...market-product-bob-watson-write-the-docs-portland-2018.json | 3 +-- ...er-documentation-kat-king-write-the-docs-portland-2018.json | 3 +-- ...ument-yourself-erin-grace-write-the-docs-portland-2018.json | 3 +-- ...nt-warning-steve-stegelin-write-the-docs-portland-2018.json | 3 +-- ...amples-shine-larry-ullman-write-the-docs-portland-2018.json | 3 +-- ...not-the-docs-havi-hoffman-write-the-docs-portland-2018.json | 3 +-- ...ou-re-wrong-jen-lambourne-write-the-docs-portland-2018.json | 3 +-- ...ite-the-docs-camille-acey-write-the-docs-portland-2018.json | 3 +-- ...-junior-writers-sarah-day-write-the-docs-portland-2018.json | 3 +-- ...tation-triage-neal-kaplan-write-the-docs-portland-2018.json | 3 +-- ...about-faqs-ashleigh-rentz-write-the-docs-portland-2018.json | 3 +-- ...new-style-guides-thursday-bram-write-the-docs-portland.json | 3 +-- ...ries-taught-me-about-writing-documentation-erin-mckean.json | 3 +-- ...ites-the-docs-beth-aitman-write-the-docs-portland-2018.json | 3 +-- ...tech-book-brian-macdonald-write-the-docs-portland-2018.json | 3 +-- 16 files changed, 16 insertions(+), 32 deletions(-) diff --git a/writethedocs-na-2018/videos/7-essential-tips-for-the-enlightened-tech-writer-ted-hudek-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/7-essential-tips-for-the-enlightened-tech-writer-ted-hudek-write-the-docs-portland-2018.json index d257517ad..cc526ff14 100644 --- a/writethedocs-na-2018/videos/7-essential-tips-for-the-enlightened-tech-writer-ted-hudek-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/7-essential-tips-for-the-enlightened-tech-writer-ted-hudek-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "These core principles have guided me during my (almost) two decades in\nthe business. I'll share some real-world stories to show what kind of\nresults you can expect.\n\nThe tips:\n\n- Just ask.\n- Listen for intent.\n- Create the minimum thing.\n- Cultivate ownership, individual and product.\n- Be a lifelong learner.\n- Opt in.\n- Use the power of storytelling.\n\nThere might even be a surprise bonus tip.\n", "copyright_text": null, - "description": "", + "description": "These core principles have guided me during my (almost) two decades in\nthe business. I'll share some real-world stories to show what kind of\nresults you can expect.\n\nThe tips:\n\n- Just ask.\n- Listen for intent.\n- Create the minimum thing.\n- Cultivate ownership, individual and product.\n- Be a lifelong learner.\n- Opt in.\n- Use the power of storytelling.\n\nThere might even be a surprise bonus tip.\n", "duration": 1843, "language": "eng", "recorded": "2018-05-08", diff --git a/writethedocs-na-2018/videos/audience-market-product-bob-watson-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/audience-market-product-bob-watson-write-the-docs-portland-2018.json index ff46e0228..eb209d7e0 100644 --- a/writethedocs-na-2018/videos/audience-market-product-bob-watson-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/audience-market-product-bob-watson-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "API documentation can been grouped into four classes\u2014Overviews,\nTutorials, How-to topics, and References. Each addresses a different\ncustomer need and each requires different amounts of time and types of\nresources to produce. However, what happens on that fateful day you find\nthat you have more documentation to write than time will allow? (As a\ntechnical writer, I call those weekdays). How can you prioritize which\ndocumentation type and how much of it should be written and which topics\nto write first?\n\nThis talk provides guidance and encouragement to technical writers to\nhelp them get the information they need to strategically get the right\ndocs to the right people at the right time\u2014and learn a little bit more\nabout their stakeholders along the way.\n", "copyright_text": null, - "description": "", + "description": "API documentation can been grouped into four classes\u2014Overviews,\nTutorials, How-to topics, and References. Each addresses a different\ncustomer need and each requires different amounts of time and types of\nresources to produce. However, what happens on that fateful day you find\nthat you have more documentation to write than time will allow? (As a\ntechnical writer, I call those weekdays). How can you prioritize which\ndocumentation type and how much of it should be written and which topics\nto write first?\n\nThis talk provides guidance and encouragement to technical writers to\nhelp them get the information they need to strategically get the right\ndocs to the right people at the right time\u2014and learn a little bit more\nabout their stakeholders along the way.\n", "duration": 1300, "language": "eng", "recorded": "2018-05-08", diff --git a/writethedocs-na-2018/videos/building-empathy-driven-developer-documentation-kat-king-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/building-empathy-driven-developer-documentation-kat-king-write-the-docs-portland-2018.json index 1dbfc0e57..baa8621ff 100644 --- a/writethedocs-na-2018/videos/building-empathy-driven-developer-documentation-kat-king-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/building-empathy-driven-developer-documentation-kat-king-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "Ever lie awake at night wondering, How do we know if our documentation\nis any good? What does \u201cgood\u201d mean, anyway? Well, you\u2019re not alone - but\nthe good news is, there\u2019s a way to find out! The secret lies in caring\nabout your developers and actively working to learn how your docs serve\nthem (or don\u2019t!)\n\nIn this talk, I\u2019ll share the story of Twilio\u2019s journey toward\nempathy-driven documentation. By leveraging direct user feedback, user\nexperience research, and constantly testing the effectiveness of the\ndocs you provide, you can learn how your users work with (and wish they\ncould work with) your docs.\n\nAlong the way I\u2019ll share a few tips about what worked well for us, what\nideas didn\u2019t pan out, and some of the documentation principles we\u2019re now\nsold on.\n", "copyright_text": null, - "description": "", + "description": "Ever lie awake at night wondering, How do we know if our documentation\nis any good? What does \u201cgood\u201d mean, anyway? Well, you\u2019re not alone - but\nthe good news is, there\u2019s a way to find out! The secret lies in caring\nabout your developers and actively working to learn how your docs serve\nthem (or don\u2019t!)\n\nIn this talk, I\u2019ll share the story of Twilio\u2019s journey toward\nempathy-driven documentation. By leveraging direct user feedback, user\nexperience research, and constantly testing the effectiveness of the\ndocs you provide, you can learn how your users work with (and wish they\ncould work with) your docs.\n\nAlong the way I\u2019ll share a few tips about what worked well for us, what\nideas didn\u2019t pan out, and some of the documentation principles we\u2019re now\nsold on.\n", "duration": 1681, "language": "eng", "recorded": "2018-05-06", diff --git a/writethedocs-na-2018/videos/document-yourself-erin-grace-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/document-yourself-erin-grace-write-the-docs-portland-2018.json index 0c82567fb..c4d6d5b08 100644 --- a/writethedocs-na-2018/videos/document-yourself-erin-grace-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/document-yourself-erin-grace-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "In a tech writer\u2019s career, creating and maintaining a great portfolio is\nas important as it is stressful. What belongs in there? What constitutes\nyour \"best work\"? What if all your work is proprietary? Do you really\nneed a portfolio if you have a great job?\n\nBuilding a portfolio is an exercise in documenting yourself: your\nwriting, your skill, your journey as a professional. Like any other kind\nof documentation, it isn't easy or intuitive to create something great.\nAnd like any other kind of documentation, it's worth doing the hard work\nto get it right.\n\nIn this talk, I cover:\n\n- Why you need a portfolio even if you have a stable job\n- How to create a well-rounded portfolio and decide what's your best\n work\n- Strategies for adding proprietary work (legally!)\n- Options to present it that aren't just a series of email attachments\n", "copyright_text": null, - "description": "", + "description": "In a tech writer\u2019s career, creating and maintaining a great portfolio is\nas important as it is stressful. What belongs in there? What constitutes\nyour \"best work\"? What if all your work is proprietary? Do you really\nneed a portfolio if you have a great job?\n\nBuilding a portfolio is an exercise in documenting yourself: your\nwriting, your skill, your journey as a professional. Like any other kind\nof documentation, it isn't easy or intuitive to create something great.\nAnd like any other kind of documentation, it's worth doing the hard work\nto get it right.\n\nIn this talk, I cover:\n\n- Why you need a portfolio even if you have a stable job\n- How to create a well-rounded portfolio and decide what's your best\n work\n- Strategies for adding proprietary work (legally!)\n- Options to present it that aren't just a series of email attachments\n", "duration": 1309, "language": "eng", "recorded": "2018-05-06", diff --git a/writethedocs-na-2018/videos/graphic-content-warning-steve-stegelin-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/graphic-content-warning-steve-stegelin-write-the-docs-portland-2018.json index 0e7332694..fa9a18204 100644 --- a/writethedocs-na-2018/videos/graphic-content-warning-steve-stegelin-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/graphic-content-warning-steve-stegelin-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "There are multiple reasons to use screenshots, from introducing new\nfeatures and helping confirm the context of content to simply breaking\nup walls of text. However, screenshots can carry a lot of overhead,\nincluding localization considerations and short shelf-lives due to\ncontinuous deployment, which may make them more effort than their worth.\nFor content that appears in context of the UI, screenshots can also be\nredundant and unnecessary. As alternatives to screenshots, there are\nseveral visual content strategies to consider to engage audiences and\nconvey and complement concepts and UIisms, including infographics,\nillustrations, and abstract \"simplified UI (SUI)\" representations. Which\nyou use depends on your intent and message.\n", "copyright_text": null, - "description": "", + "description": "There are multiple reasons to use screenshots, from introducing new\nfeatures and helping confirm the context of content to simply breaking\nup walls of text. However, screenshots can carry a lot of overhead,\nincluding localization considerations and short shelf-lives due to\ncontinuous deployment, which may make them more effort than their worth.\nFor content that appears in context of the UI, screenshots can also be\nredundant and unnecessary. As alternatives to screenshots, there are\nseveral visual content strategies to consider to engage audiences and\nconvey and complement concepts and UIisms, including infographics,\nillustrations, and abstract \"simplified UI (SUI)\" representations. Which\nyou use depends on your intent and message.\n", "duration": 1248, "language": "eng", "recorded": "2018-05-06", diff --git a/writethedocs-na-2018/videos/making-your-code-examples-shine-larry-ullman-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/making-your-code-examples-shine-larry-ullman-write-the-docs-portland-2018.json index 997450eda..30e839726 100644 --- a/writethedocs-na-2018/videos/making-your-code-examples-shine-larry-ullman-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/making-your-code-examples-shine-larry-ullman-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "Thorough and optimal technical documentation often requires not just an\nAPI reference of endpoints and parameters, or long contextual\ninstructions, but also code examples that users can cut and paste into\ntheir applications. As a technical writer at Stripe, I\u2019m partially\nresponsible for maintaining 150 code examples, each of which needs to be\nin 8 programming languages. In this presentation, I\u2019ll explain the\nprocesses we\u2019re using, the hurdles we\u2019re facing, and the solutions we\u2019ve\ndevised thus far to make and maintain code examples that really shine.\n\nSpecific concepts covered include:\n\n- Defining a style guide for your code\n- Generating code examples programmatically\n- Testing examples to ensure they work\n- Using common snippets to save time\n- Enhancing examples for a better user experience\n\nAlthough we haven\u2019t solved all our problems in this area, we\u2019ve made\ngreat progress with great results, and I look forward to sharing our\nbest policies and practices.\n", "copyright_text": null, - "description": "", + "description": "Thorough and optimal technical documentation often requires not just an\nAPI reference of endpoints and parameters, or long contextual\ninstructions, but also code examples that users can cut and paste into\ntheir applications. As a technical writer at Stripe, I\u2019m partially\nresponsible for maintaining 150 code examples, each of which needs to be\nin 8 programming languages. In this presentation, I\u2019ll explain the\nprocesses we\u2019re using, the hurdles we\u2019re facing, and the solutions we\u2019ve\ndevised thus far to make and maintain code examples that really shine.\n\nSpecific concepts covered include:\n\n- Defining a style guide for your code\n- Generating code examples programmatically\n- Testing examples to ensure they work\n- Using common snippets to save time\n- Enhancing examples for a better user experience\n\nAlthough we haven\u2019t solved all our problems in this area, we\u2019ve made\ngreat progress with great results, and I look forward to sharing our\nbest policies and practices.\n", "duration": 1674, "language": "eng", "recorded": "2018-05-08", diff --git a/writethedocs-na-2018/videos/not-the-docs-havi-hoffman-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/not-the-docs-havi-hoffman-write-the-docs-portland-2018.json index da97b6f67..5f615db64 100644 --- a/writethedocs-na-2018/videos/not-the-docs-havi-hoffman-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/not-the-docs-havi-hoffman-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "I\u2019d like to talk about the role of an editor and the art of enabling\nhumans to create, publish and present technical content in a variety of\nmedia. Primarily in text, in the context of a blog or other \u2018managed\u2019\ncalendar-driven web publications. Not technical documentation. Sometimes\nit\u2019s a mighty fine line between docs and blogs, but I think we can and\nshould differentiate.\n\nThis talk will explore principles and patterns of kind, effective\neditorial practice, and nuances of voice, civility, and clear\ncommunication, as they play out when working with a diverse distributed\nroster of authors, many of whom are non-native English speakers or\nfirst-time storytellers.\n\nI believe there\u2019s as much appetite for diversity of voice and point of\nview in blogging about software development as there is in speaking\nabout it at developer conferences. And I\u2019ve got some observations to\nshare about how we can cultivate that.\n", "copyright_text": null, - "description": "", + "description": "I\u2019d like to talk about the role of an editor and the art of enabling\nhumans to create, publish and present technical content in a variety of\nmedia. Primarily in text, in the context of a blog or other \u2018managed\u2019\ncalendar-driven web publications. Not technical documentation. Sometimes\nit\u2019s a mighty fine line between docs and blogs, but I think we can and\nshould differentiate.\n\nThis talk will explore principles and patterns of kind, effective\neditorial practice, and nuances of voice, civility, and clear\ncommunication, as they play out when working with a diverse distributed\nroster of authors, many of whom are non-native English speakers or\nfirst-time storytellers.\n\nI believe there\u2019s as much appetite for diversity of voice and point of\nview in blogging about software development as there is in speaking\nabout it at developer conferences. And I\u2019ve got some observations to\nshare about how we can cultivate that.\n", "duration": 1593, "language": "eng", "recorded": "2018-05-06", diff --git a/writethedocs-na-2018/videos/research-like-you-re-wrong-jen-lambourne-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/research-like-you-re-wrong-jen-lambourne-write-the-docs-portland-2018.json index 6c331ff9e..b2c2a7829 100644 --- a/writethedocs-na-2018/videos/research-like-you-re-wrong-jen-lambourne-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/research-like-you-re-wrong-jen-lambourne-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "We all want to create docs that help our users. We know good research\nhelps us to give our readers what they need and poor research can weaken\nour docs so it\u2019s time to step up our research game.\n\nGrounded in the things I\u2019ve learnt (read: mistakes I\u2019ve made) from my\ntime writing open source documentation for the UK government at\nGovernment Digital Service (GDS), this talk will look at:\n\n- deciding what - and how - to research\n- interviewing, simulation and content evaluation techniques\n- distinguishing user \u2018needs\u2019 from \u2018wants\u2019\n- how the Hawthorne effect can influence research\n- how to feed findings into product and content development\n\nThroughout it all, we\u2019ll cover strategies to avoid common pitfalls, how\nto avoid users telling you what you want to hear, how to manage research\nwith no extra budget and, when it\u2019s all done, how to turn all that\nqualitative data into tangible content changes that have a genuine\nimpact for users.\n", "copyright_text": null, - "description": "", + "description": "We all want to create docs that help our users. We know good research\nhelps us to give our readers what they need and poor research can weaken\nour docs so it\u2019s time to step up our research game.\n\nGrounded in the things I\u2019ve learnt (read: mistakes I\u2019ve made) from my\ntime writing open source documentation for the UK government at\nGovernment Digital Service (GDS), this talk will look at:\n\n- deciding what - and how - to research\n- interviewing, simulation and content evaluation techniques\n- distinguishing user \u2018needs\u2019 from \u2018wants\u2019\n- how the Hawthorne effect can influence research\n- how to feed findings into product and content development\n\nThroughout it all, we\u2019ll cover strategies to avoid common pitfalls, how\nto avoid users telling you what you want to hear, how to manage research\nwith no extra budget and, when it\u2019s all done, how to turn all that\nqualitative data into tangible content changes that have a genuine\nimpact for users.\n", "duration": 1611, "language": "eng", "recorded": "2018-05-06", diff --git a/writethedocs-na-2018/videos/rewrite-the-docs-camille-acey-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/rewrite-the-docs-camille-acey-write-the-docs-portland-2018.json index 4f352b88e..b9c7677fe 100644 --- a/writethedocs-na-2018/videos/rewrite-the-docs-camille-acey-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/rewrite-the-docs-camille-acey-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "Years of being one of the \"technical people\" in activist circles\nresulted in my being continually called on to help community groups and\nfellow organizers understand and more correctly wield technology in\nservice of their mission. Using my blogpost \"Three Tips for Providing\nTech Help to Non-Profits and Other Such Organizations\" as a point of\ndeparture, I will share my experience and derived best practices.\n\nFrom \"basics\", like how to use documents and spreadsheets, to working\nwith databases and understanding security, I have given assistance to a\ngreat many groups and the most important part is always the\ndocumentation that I leave behind. I can rarely ever just point people\nto the official software or open source project documentation, I almost\nalways have to rewrite the docs for them in simple language that\nreferences their specific use case.\n\nI wish to help community and activist groups make better technical\nchoices so that they feel more in control of the technologies they use.\nMy hope is that in sharing my experiences, I can engage in a deeper\ndialogue with the technical documentation community about how we can\nmake technical documentation more accessible, easier to re-use, and\nempowering.\n", "copyright_text": null, - "description": "", + "description": "Years of being one of the \"technical people\" in activist circles\nresulted in my being continually called on to help community groups and\nfellow organizers understand and more correctly wield technology in\nservice of their mission. Using my blogpost \"Three Tips for Providing\nTech Help to Non-Profits and Other Such Organizations\" as a point of\ndeparture, I will share my experience and derived best practices.\n\nFrom \"basics\", like how to use documents and spreadsheets, to working\nwith databases and understanding security, I have given assistance to a\ngreat many groups and the most important part is always the\ndocumentation that I leave behind. I can rarely ever just point people\nto the official software or open source project documentation, I almost\nalways have to rewrite the docs for them in simple language that\nreferences their specific use case.\n\nI wish to help community and activist groups make better technical\nchoices so that they feel more in control of the technologies they use.\nMy hope is that in sharing my experiences, I can engage in a deeper\ndialogue with the technical documentation community about how we can\nmake technical documentation more accessible, easier to re-use, and\nempowering.\n", "duration": 1100, "language": "eng", "recorded": "2018-05-06", diff --git a/writethedocs-na-2018/videos/starting-from-scratch-finding-and-hiring-junior-writers-sarah-day-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/starting-from-scratch-finding-and-hiring-junior-writers-sarah-day-write-the-docs-portland-2018.json index 6fc57ad33..5b80ce8ff 100644 --- a/writethedocs-na-2018/videos/starting-from-scratch-finding-and-hiring-junior-writers-sarah-day-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/starting-from-scratch-finding-and-hiring-junior-writers-sarah-day-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "Our team has the classic documentation problem--a huge backlog of work\nand not enough writers. Enter the documentation internship program,\nwhich connected us with junior and aspiring technical writers and got us\nheadcount fast.\n\nThis talk will teach you how we recruited, interviewed, and hired\ninexperienced writers, and taught them the basics of technical writing\u2026\nall without damaging our velocity.\n\nI\u2019ll focus specifically on how our job pitch got us applicants from a\nwide array of backgrounds, from screenwriters to college students, how\nwe made sense of the answers we got through an unpredictable set of\ninterviews, and how we onboarded writers with strong skills and\naptitude, but no real-world experience.\n", "copyright_text": null, - "description": "", + "description": "Our team has the classic documentation problem--a huge backlog of work\nand not enough writers. Enter the documentation internship program,\nwhich connected us with junior and aspiring technical writers and got us\nheadcount fast.\n\nThis talk will teach you how we recruited, interviewed, and hired\ninexperienced writers, and taught them the basics of technical writing\u2026\nall without damaging our velocity.\n\nI\u2019ll focus specifically on how our job pitch got us applicants from a\nwide array of backgrounds, from screenwriters to college students, how\nwe made sense of the answers we got through an unpredictable set of\ninterviews, and how we onboarded writers with strong skills and\naptitude, but no real-world experience.\n", "duration": 1721, "language": "eng", "recorded": "2018-05-08", diff --git a/writethedocs-na-2018/videos/the-art-and-practice-of-documentation-triage-neal-kaplan-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/the-art-and-practice-of-documentation-triage-neal-kaplan-write-the-docs-portland-2018.json index fefd06675..572ec89dd 100644 --- a/writethedocs-na-2018/videos/the-art-and-practice-of-documentation-triage-neal-kaplan-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/the-art-and-practice-of-documentation-triage-neal-kaplan-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "Congratulations! Someone realizes your awesome product needs equally\nawesome documentation, and you\u2019ve earned the job! It\u2019s an exciting new\nrole, with new goals and challenges.\n\nCue the panic: There are too many things to do! Where do I start? How\ncan I succeed in this role?\n\nI\u2019ve been there before. In fact, I\u2019ve done it multiple times. Like\nmedical triage, you won\u2019t have a lot of time to think before you dive in\nand get to work. It\u2019s stressful, even if there are no lives at stake!\n\nBut you can be fast and smart. I\u2019ll tell you how to get started (audit\nthe existing content, create a list of requirements for documentation\ntools, ruthlessly prioritize a huge list of tasks) and how to keep going\n(build relationships with coworkers in customer-facing roles to learn\nwhat your customers really need from docs, take a moment to pat yourself\non the back every now and then). I\u2019ll also admit to mistakes I\u2019ve made,\nand how I\u2019ve learned to avoid them (like trying to do everything myself,\nor thinking that time spent planning is taking away from \u201creal work\u201d).\n\nYour new role will require hard work, but a bit of advice can help you\nget started, stay motivated, and avoid pitfalls along the way.\n", "copyright_text": null, - "description": "", + "description": "Congratulations! Someone realizes your awesome product needs equally\nawesome documentation, and you\u2019ve earned the job! It\u2019s an exciting new\nrole, with new goals and challenges.\n\nCue the panic: There are too many things to do! Where do I start? How\ncan I succeed in this role?\n\nI\u2019ve been there before. In fact, I\u2019ve done it multiple times. Like\nmedical triage, you won\u2019t have a lot of time to think before you dive in\nand get to work. It\u2019s stressful, even if there are no lives at stake!\n\nBut you can be fast and smart. I\u2019ll tell you how to get started (audit\nthe existing content, create a list of requirements for documentation\ntools, ruthlessly prioritize a huge list of tasks) and how to keep going\n(build relationships with coworkers in customer-facing roles to learn\nwhat your customers really need from docs, take a moment to pat yourself\non the back every now and then). I\u2019ll also admit to mistakes I\u2019ve made,\nand how I\u2019ve learned to avoid them (like trying to do everything myself,\nor thinking that time spent planning is taking away from \u201creal work\u201d).\n\nYour new role will require hard work, but a bit of advice can help you\nget started, stay motivated, and avoid pitfalls along the way.\n", "duration": 1603, "language": "eng", "recorded": "2018-05-08", diff --git a/writethedocs-na-2018/videos/the-facts-about-faqs-ashleigh-rentz-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/the-facts-about-faqs-ashleigh-rentz-write-the-docs-portland-2018.json index 55def57ac..dadbac40d 100644 --- a/writethedocs-na-2018/videos/the-facts-about-faqs-ashleigh-rentz-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/the-facts-about-faqs-ashleigh-rentz-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "Ah, good old FAQs: the internet\u2019s native documentation format. In this\ntalk, we\u2019ll explore various questions we might frequently ask ourselves\nabout FAQs, such as:\n\n- Why do readers always seem to want them even though they\u2019re routinely\n out of date?\n- Why do some readers ignore our carefully crafted pages and use these\n giant walls of text as a starting point instead?\n- What are some strategies for keeping FAQs up to date?\n- What\u2019s the #1 thing FAQs do RIGHT?\n- How can we make FAQs more user-friendly?\n- Do we even actually need FAQs?\n\n(Caution: May contain opinions.)\n", "copyright_text": null, - "description": "", + "description": "Ah, good old FAQs: the internet\u2019s native documentation format. In this\ntalk, we\u2019ll explore various questions we might frequently ask ourselves\nabout FAQs, such as:\n\n- Why do readers always seem to want them even though they\u2019re routinely\n out of date?\n- Why do some readers ignore our carefully crafted pages and use these\n giant walls of text as a starting point instead?\n- What are some strategies for keeping FAQs up to date?\n- What\u2019s the #1 thing FAQs do RIGHT?\n- How can we make FAQs more user-friendly?\n- Do we even actually need FAQs?\n\n(Caution: May contain opinions.)\n", "duration": 1532, "language": "eng", "recorded": "2018-05-06", diff --git a/writethedocs-na-2018/videos/what-they-don-t-tell-you-about-creating-new-style-guides-thursday-bram-write-the-docs-portland.json b/writethedocs-na-2018/videos/what-they-don-t-tell-you-about-creating-new-style-guides-thursday-bram-write-the-docs-portland.json index 26f71d06f..5171a813a 100644 --- a/writethedocs-na-2018/videos/what-they-don-t-tell-you-about-creating-new-style-guides-thursday-bram-write-the-docs-portland.json +++ b/writethedocs-na-2018/videos/what-they-don-t-tell-you-about-creating-new-style-guides-thursday-bram-write-the-docs-portland.json @@ -1,7 +1,6 @@ { - "abstract": "Style guides are a key tool for many documentarians \u2014 they guarantee\nconsistency, streamline onboarding, and even improve the documentation\nnon- technical writers create.\n\nWhether you're creating an internal style guide or a commercially\navailable reference, though, there are plenty of pitfalls. In this talk,\nwe'll cover:\n\n- style guide assumptions (and how to avoid them)\n- jargon, slang, idioms, and other words with multiple meanings\n- inclusion, sensitivity readings, and generally making sure you know\n how other people hear terms\n- teaching style across a team\n", "copyright_text": null, - "description": "", + "description": "Style guides are a key tool for many documentarians \u2014 they guarantee\nconsistency, streamline onboarding, and even improve the documentation\nnon- technical writers create.\n\nWhether you're creating an internal style guide or a commercially\navailable reference, though, there are plenty of pitfalls. In this talk,\nwe'll cover:\n\n- style guide assumptions (and how to avoid them)\n- jargon, slang, idioms, and other words with multiple meanings\n- inclusion, sensitivity readings, and generally making sure you know\n how other people hear terms\n- teaching style across a team\n", "duration": 1354, "language": "eng", "recorded": "2018-05-08", diff --git a/writethedocs-na-2018/videos/what-writing-dictionaries-taught-me-about-writing-documentation-erin-mckean.json b/writethedocs-na-2018/videos/what-writing-dictionaries-taught-me-about-writing-documentation-erin-mckean.json index 7095df74e..34feaa608 100644 --- a/writethedocs-na-2018/videos/what-writing-dictionaries-taught-me-about-writing-documentation-erin-mckean.json +++ b/writethedocs-na-2018/videos/what-writing-dictionaries-taught-me-about-writing-documentation-erin-mckean.json @@ -1,7 +1,6 @@ { - "abstract": "Before becoming a full-time software developer, I spent more than twenty\nyears working on dictionaries and other reference books. Reference books\nand dictionaries have a lot of similarities with documentation: they're\nboth genres of writing that aim to explain and educate, and are aimed at\nan audience that is largely goal-oriented and impatient. In this talk,\nI'll give a little bit of background on how reference books\n(particularly dictionaries and thesauruses) are made, talk about my\nexperience in publishing has informed writing documentation and\ntutorials (and working with Swagger/OpenAPI), and give some examples of\nhabits I had to un-learn, too!\n", "copyright_text": null, - "description": "", + "description": "Before becoming a full-time software developer, I spent more than twenty\nyears working on dictionaries and other reference books. Reference books\nand dictionaries have a lot of similarities with documentation: they're\nboth genres of writing that aim to explain and educate, and are aimed at\nan audience that is largely goal-oriented and impatient. In this talk,\nI'll give a little bit of background on how reference books\n(particularly dictionaries and thesauruses) are made, talk about my\nexperience in publishing has informed writing documentation and\ntutorials (and working with Swagger/OpenAPI), and give some examples of\nhabits I had to un-learn, too!\n", "duration": 1558, "language": "eng", "recorded": "2018-05-08", diff --git a/writethedocs-na-2018/videos/who-writes-the-docs-beth-aitman-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/who-writes-the-docs-beth-aitman-write-the-docs-portland-2018.json index fae253850..cff612bde 100644 --- a/writethedocs-na-2018/videos/who-writes-the-docs-beth-aitman-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/who-writes-the-docs-beth-aitman-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "In the wider tech writer world, it\u2019s still common to hear tech writers\nbe certain that developers can\u2019t write good help: the prevailing sense\nis \u201cOnly we can do this.\u201d But those same tech writers often feel under\nthreat in their jobs - feeling like their organisation doesn\u2019t see their\nvalue, doesn\u2019t understand what they do.\n\nWho *should* write the docs? Should all developers write docs as a\nmatter of course? Is it even worthwhile having specialist writers?\n\nIn this talk I\u2019ll try to find some answers to these questions, based on\nmy experience working in many teams - both in teams that have valued\ntech writing and in teams that haven\u2019t. I\u2019ll talk about the\n\u2018documentarian\u2019 mindset and how that contributes to better software, no\nmatter what your job title is.\n\nI\u2019ll also explore the benefits that come from specialist writers and\ngeneralist developers working together. And I\u2019ll share the ways I\u2019ve\nfound that people with specialist writer skills (whether they\u2019re\ndevelopers, tech writers, or other roles) can make the biggest\ndifference to user experience, and through that to their organisations.\n", "copyright_text": null, - "description": "", + "description": "In the wider tech writer world, it\u2019s still common to hear tech writers\nbe certain that developers can\u2019t write good help: the prevailing sense\nis \u201cOnly we can do this.\u201d But those same tech writers often feel under\nthreat in their jobs - feeling like their organisation doesn\u2019t see their\nvalue, doesn\u2019t understand what they do.\n\nWho *should* write the docs? Should all developers write docs as a\nmatter of course? Is it even worthwhile having specialist writers?\n\nIn this talk I\u2019ll try to find some answers to these questions, based on\nmy experience working in many teams - both in teams that have valued\ntech writing and in teams that haven\u2019t. I\u2019ll talk about the\n\u2018documentarian\u2019 mindset and how that contributes to better software, no\nmatter what your job title is.\n\nI\u2019ll also explore the benefits that come from specialist writers and\ngeneralist developers working together. And I\u2019ll share the ways I\u2019ve\nfound that people with specialist writer skills (whether they\u2019re\ndevelopers, tech writers, or other roles) can make the biggest\ndifference to user experience, and through that to their organisations.\n", "duration": 1416, "language": "eng", "recorded": "2018-05-06", diff --git a/writethedocs-na-2018/videos/writing-the-next-great-tech-book-brian-macdonald-write-the-docs-portland-2018.json b/writethedocs-na-2018/videos/writing-the-next-great-tech-book-brian-macdonald-write-the-docs-portland-2018.json index 7679bb6fe..e4b12d4b9 100644 --- a/writethedocs-na-2018/videos/writing-the-next-great-tech-book-brian-macdonald-write-the-docs-portland-2018.json +++ b/writethedocs-na-2018/videos/writing-the-next-great-tech-book-brian-macdonald-write-the-docs-portland-2018.json @@ -1,7 +1,6 @@ { - "abstract": "You have an idea for the next great technical book. Maybe you're excited\nabout a new technology that nobody's written about yet. Maybe you're\nunimpressed with the books that are out there on your favorite topic.\nMaybe writing a book is on your bucket list. This session will help your\nidea reach its potential as a published book. Technical publishing is an\nopaque process with a lot of moving parts, which can be confusing for\noutsiders to navigate. This session will guide you through the steps you\nshould take to turn an idea into a proposal that a publisher will\naccept, and what to expect from the publishing experience.\n\nCreating a great technical book takes more than a good idea. It also\nrequires a knowledge of the market, to determine whether there's an\naudience willing to buy, or whether the space is too crowded to accept\nnew entries. Publishers vary in their approach and target markets, so\nyou need to determine which one will provide the best chance of success.\nSelf-publishing is an option, but carries its own risks and benefits.\nDoing the setup work that you may not have thought about yet will help\nyou create a proposal that will appeal to publishers, and will also make\nthe writing process easier.\n\nOnce you have a contract with a publisher, or have decided to\nself-publish, it's more than just a matter of putting the words in\norder. Finding the right environment, setting a schedule, and\ncommunicating with your editor are all critical to success. This session\nwill explain how the process works, highlight the parts you may not\nknow, and give you advice on how not to get overwhelmed by your project.\n", "copyright_text": null, - "description": "", + "description": "You have an idea for the next great technical book. Maybe you're excited\nabout a new technology that nobody's written about yet. Maybe you're\nunimpressed with the books that are out there on your favorite topic.\nMaybe writing a book is on your bucket list. This session will help your\nidea reach its potential as a published book. Technical publishing is an\nopaque process with a lot of moving parts, which can be confusing for\noutsiders to navigate. This session will guide you through the steps you\nshould take to turn an idea into a proposal that a publisher will\naccept, and what to expect from the publishing experience.\n\nCreating a great technical book takes more than a good idea. It also\nrequires a knowledge of the market, to determine whether there's an\naudience willing to buy, or whether the space is too crowded to accept\nnew entries. Publishers vary in their approach and target markets, so\nyou need to determine which one will provide the best chance of success.\nSelf-publishing is an option, but carries its own risks and benefits.\nDoing the setup work that you may not have thought about yet will help\nyou create a proposal that will appeal to publishers, and will also make\nthe writing process easier.\n\nOnce you have a contract with a publisher, or have decided to\nself-publish, it's more than just a matter of putting the words in\norder. Finding the right environment, setting a schedule, and\ncommunicating with your editor are all critical to success. This session\nwill explain how the process works, highlight the parts you may not\nknow, and give you advice on how not to get overwhelmed by your project.\n", "duration": 1596, "language": "eng", "recorded": "2018-05-06", From 2efccd849e3528a822b88dbd1069cc099bfd9ce7 Mon Sep 17 00:00:00 2001 From: Jon Banafato Date: Mon, 29 Jul 2024 16:09:09 -0400 Subject: [PATCH 4/7] Write The Docs NA 2017: move talk abstracts into description field --- ...-2017-bootstrapping-docs-at-a-startup-by-jesse-seldess.json | 3 +-- ...tion-for-your-doc-site-5-best-practices-by-tom-johnson.json | 3 +-- ...7-caring-systems-documentation-as-care-by-amelia-abreu.json | 3 +-- ...do-you-know-a-runbook-from-a-flip-book-by-andrea-longo.json | 3 +-- ...r-messages-being-humble-human-and-helpful-by-kate-voss.json | 3 +-- ...nd-2017-even-naming-this-talk-is-hard-by-ruthie-bendor.json | 3 +-- ...ryone-s-a-player-in-a-mid-90s-mud-by-kenzie-woodbridge.json | 3 +-- ...gent-documents-and-the-verifiability-crisis-in-science.json | 3 +-- ...iewing-and-hiring-technical-writers-by-sam-faktorovich.json | 3 +-- ...nity-members-were-harmed-by-lindsay-muscato-ryan-pitts.json | 3 +-- ...2017-only-interesting-conversations-by-matthew-buttler.json | 3 +-- ...-start-with-the-tasks-not-the-endpoints-by-sarah-hersh.json | 3 +-- ...testing-it-s-not-just-for-code-anymore-by-lyzi-diamond.json | 3 +-- ...ocs-portland-2017-the-wisdom-of-crowds-by-ingrid-towey.json | 3 +-- ...ntation-like-code-a-practical-account-by-jodie-putrino.json | 3 +-- ...rtland-2017-you-have-already-succeeded-by-christy-lutz.json | 3 +-- 16 files changed, 16 insertions(+), 32 deletions(-) diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-bootstrapping-docs-at-a-startup-by-jesse-seldess.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-bootstrapping-docs-at-a-startup-by-jesse-seldess.json index 4ac9d1b61..8fd4fd11c 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-bootstrapping-docs-at-a-startup-by-jesse-seldess.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-bootstrapping-docs-at-a-startup-by-jesse-seldess.json @@ -1,7 +1,6 @@ { - "abstract": "How do you \u201cbootstrap docs\u201d? In this talk, I will walk through how to\nbuild essential docs for an early stage startup that lays a strong\nfoundation for continuous improvement and expansion. The story will be\ntold through my experiences building docs from scratch for CockroachDB\n(https://www.cockroachlabs.com), a next-generation open source database.\n\nWhen I joined Cockroach Labs as its first technical writer, CockroachDB\nhad been in development for nearly two years and had 15 engineers and\n60+ open source developers contributing to it. I needed to build a\ndocumentation structure and process that would be lightweight enough for\ndevelopers to contribute to and flexible enough to apply to the product\n(and team) years down the road.\n\nThis talk will walk the audience through the process of learning a new\nproduct and development team, and allowing that information to guide the\ninformation architecture and tool selection process.\n\nTopics will include: - How do you learn a new product, and why is it\nessential to understand its market fit? - How do you learn about your\nusers - who are they, what are their primary pain points, and what do\nthey need most from docs? - How do you choose tools and workflows for\nbuilding your initial docs architecture? - How do you iterate on,\nimprove, and expand your docs, and harness contributors to do the same?\n", "copyright_text": null, - "description": "", + "description": "How do you \u201cbootstrap docs\u201d? In this talk, I will walk through how to\nbuild essential docs for an early stage startup that lays a strong\nfoundation for continuous improvement and expansion. The story will be\ntold through my experiences building docs from scratch for CockroachDB\n(https://www.cockroachlabs.com), a next-generation open source database.\n\nWhen I joined Cockroach Labs as its first technical writer, CockroachDB\nhad been in development for nearly two years and had 15 engineers and\n60+ open source developers contributing to it. I needed to build a\ndocumentation structure and process that would be lightweight enough for\ndevelopers to contribute to and flexible enough to apply to the product\n(and team) years down the road.\n\nThis talk will walk the audience through the process of learning a new\nproduct and development team, and allowing that information to guide the\ninformation architecture and tool selection process.\n\nTopics will include: - How do you learn a new product, and why is it\nessential to understand its market fit? - How do you learn about your\nusers - who are they, what are their primary pain points, and what do\nthey need most from docs? - How do you choose tools and workflows for\nbuilding your initial docs architecture? - How do you iterate on,\nimprove, and expand your docs, and harness contributors to do the same?\n", "duration": 1759, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-building-navigation-for-your-doc-site-5-best-practices-by-tom-johnson.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-building-navigation-for-your-doc-site-5-best-practices-by-tom-johnson.json index 2c0e45ca0..ccbc252ad 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-building-navigation-for-your-doc-site-5-best-practices-by-tom-johnson.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-building-navigation-for-your-doc-site-5-best-practices-by-tom-johnson.json @@ -1,7 +1,6 @@ { - "abstract": "Although users typically arrive at doc websites in a confused and\nimpatient state, not sure of where to find what they're looking for,\ngood navigation can guide them to the right answer. Good navigation\nanticipates users' needs, provides links in commonly viewed places, and\nbrings the right topic into the foreground amid hundreds of other\ntopics.\n\nAs you build out the navigation for your doc site, follow these 5 design\nprinciples:\n\n- **Entry point**. Design the entry point to your system to orient\n users and allow them to easily get started.\n\n- **Hierarchy**. Create a hierarchical outline of the content to help\n users both understand and visualize the body of information.\n\n- **Modularity**. Break up content into independent topics that can be\n viewed, understood, and updated independent of the whole.\n\n- **Progressive disclosure**. Layer the information so that you don't\n present everything at once but rather make some content available\n only at secondary or tertiary levels.\n\n- **Wayfinding**. Provide navigational signposts :raw-latex:`\\u2`014\n such as breadcrumbs and workflow maps :raw-latex:`\\u2`014 to help\n orient users as to where they are in a larger system.\n", "copyright_text": null, - "description": "", + "description": "Although users typically arrive at doc websites in a confused and\nimpatient state, not sure of where to find what they're looking for,\ngood navigation can guide them to the right answer. Good navigation\nanticipates users' needs, provides links in commonly viewed places, and\nbrings the right topic into the foreground amid hundreds of other\ntopics.\n\nAs you build out the navigation for your doc site, follow these 5 design\nprinciples:\n\n- **Entry point**. Design the entry point to your system to orient\n users and allow them to easily get started.\n\n- **Hierarchy**. Create a hierarchical outline of the content to help\n users both understand and visualize the body of information.\n\n- **Modularity**. Break up content into independent topics that can be\n viewed, understood, and updated independent of the whole.\n\n- **Progressive disclosure**. Layer the information so that you don't\n present everything at once but rather make some content available\n only at secondary or tertiary levels.\n\n- **Wayfinding**. Provide navigational signposts — \n such as breadcrumbs and workflow maps — to help\n orient users as to where they are in a larger system.\n", "duration": 1279, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-caring-systems-documentation-as-care-by-amelia-abreu.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-caring-systems-documentation-as-care-by-amelia-abreu.json index 68794ff2f..5906a97e6 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-caring-systems-documentation-as-care-by-amelia-abreu.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-caring-systems-documentation-as-care-by-amelia-abreu.json @@ -1,7 +1,6 @@ { - "abstract": "All humans require care. Writing and maintaining documentation is a form\nof care: good documentation can make us feel cared-for, and we, as\nwriters, can take satisfaction from empathizing with the end users of\nour work, and performing the caring work of documentation. By exploring\nand acknowledging the relationship between care, documentation, and\ntechnology, I argue, we can better understand and advocate for the value\nof our work. More so, understanding the importance of care allows us to\nwork better.\n\nThis talk illustrates how the work of documentation is care work, and\nexplores the ethical, philosophical and economic dimensions of care in\nrelationship to technical writing and documentation. I'll share findings\nand case studies from my own consulting practice, and explore patterns\n(and anti-patterns) I've observed around documentation and care. Then,\nto spur small group discussions, I'll share design principles for\ndocumentation as care.\n", "copyright_text": null, - "description": "", + "description": "All humans require care. Writing and maintaining documentation is a form\nof care: good documentation can make us feel cared-for, and we, as\nwriters, can take satisfaction from empathizing with the end users of\nour work, and performing the caring work of documentation. By exploring\nand acknowledging the relationship between care, documentation, and\ntechnology, I argue, we can better understand and advocate for the value\nof our work. More so, understanding the importance of care allows us to\nwork better.\n\nThis talk illustrates how the work of documentation is care work, and\nexplores the ethical, philosophical and economic dimensions of care in\nrelationship to technical writing and documentation. I'll share findings\nand case studies from my own consulting practice, and explore patterns\n(and anti-patterns) I've observed around documentation and care. Then,\nto spur small group discussions, I'll share design principles for\ndocumentation as care.\n", "duration": 1238, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-do-you-know-a-runbook-from-a-flip-book-by-andrea-longo.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-do-you-know-a-runbook-from-a-flip-book-by-andrea-longo.json index c3ec580ff..04790db0a 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-do-you-know-a-runbook-from-a-flip-book-by-andrea-longo.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-do-you-know-a-runbook-from-a-flip-book-by-andrea-longo.json @@ -1,7 +1,6 @@ { - "abstract": "Come along on a tour of common types of documentation system\nadministrators use to get their jobs done.\n\nAs an enterprise software developer, system administrators are my\ncustomers and colleagues. In this session, learn not just what gets\nused, but also what internal and informal sources to look for to create\nbetter docs. I'll share what I've learned sysadmins want from the\nwritten information they rely on daily. I'll also talk about what ops\nteams write for themselves that can add important details to your\ndocuments.\n\nWe'll go beyond glossy presentation slides of instructor-led training to\ndelve into what's meaningful for day-to-day tasks. For example,\nintegration and migration: to accomplish this smoothly, sysadmins need\nreferences and examples to install, configure, and customize new tools\nto work with existing systems. Tutorials can show how, real-world\nconfiguration examples show what, and cookbooks provide ready-made\nexamples to customize as needed. Deployment checklists ensure the\nrollout goes smoothly.\n\nEmergencies can happen at any hour:raw-latex:`\\u2`014which is why\nrunbooks can be so valuable. With step-by-step details so staff can\nrespond without making mistakes. A junior engineer can resolve an issue\nwithout calling a developer for help. Manifests, dependency lists, and\nlogs become necessary adjuncts to documentation, providing critical data\nfor root cause analysis.\n\nLearn about these sources, not just how others use them, but where you\ncan find valuable detail to enhance the documents you write for\noperations.\n", "copyright_text": null, - "description": "", + "description": "Come along on a tour of common types of documentation system\nadministrators use to get their jobs done.\n\nAs an enterprise software developer, system administrators are my\ncustomers and colleagues. In this session, learn not just what gets\nused, but also what internal and informal sources to look for to create\nbetter docs. I'll share what I've learned sysadmins want from the\nwritten information they rely on daily. I'll also talk about what ops\nteams write for themselves that can add important details to your\ndocuments.\n\nWe'll go beyond glossy presentation slides of instructor-led training to\ndelve into what's meaningful for day-to-day tasks. For example,\nintegration and migration: to accomplish this smoothly, sysadmins need\nreferences and examples to install, configure, and customize new tools\nto work with existing systems. Tutorials can show how, real-world\nconfiguration examples show what, and cookbooks provide ready-made\nexamples to customize as needed. Deployment checklists ensure the\nrollout goes smoothly.\n\nEmergencies can happen at any hour — which is why\nrunbooks can be so valuable. With step-by-step details so staff can\nrespond without making mistakes. A junior engineer can resolve an issue\nwithout calling a developer for help. Manifests, dependency lists, and\nlogs become necessary adjuncts to documentation, providing critical data\nfor root cause analysis.\n\nLearn about these sources, not just how others use them, but where you\ncan find valuable detail to enhance the documents you write for\noperations.\n", "duration": 1659, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-error-messages-being-humble-human-and-helpful-by-kate-voss.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-error-messages-being-humble-human-and-helpful-by-kate-voss.json index e4b0f8315..c28de0615 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-error-messages-being-humble-human-and-helpful-by-kate-voss.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-error-messages-being-humble-human-and-helpful-by-kate-voss.json @@ -1,7 +1,6 @@ { - "abstract": "Writers often forget that users are more likely to see error messages,\ntooltips, and helper text than to search for documentation. But these\nbits of microcopy are actually an opportunity to communicate and connect\nwith users when they most need it. Most errors say that something went\nwrong, but the user doesn''t know if it''s their fault or what to do\nabout it. As writers, designers, and developers, we need to help them\nfix the problem and teach them what to do next time.\n\nMicrocopy is also a chance to create a friendly relationship and\nestablish your brand with your audience. Users are less likely to get\nfrustrated if the error message has a personal and human sentiment than\nif it merely says \"ACCESS DENIED\", or \"FORBIDDEN ACTION\".\n\nIn this talk I show how making error message Humble, Human, and Helpful\nis critical to making your users Happy. We''ll laugh at a few bad\nerrors, and learn from the good error messages and microcopy.\n", "copyright_text": null, - "description": "", + "description": "Writers often forget that users are more likely to see error messages,\ntooltips, and helper text than to search for documentation. But these\nbits of microcopy are actually an opportunity to communicate and connect\nwith users when they most need it. Most errors say that something went\nwrong, but the user doesn''t know if it''s their fault or what to do\nabout it. As writers, designers, and developers, we need to help them\nfix the problem and teach them what to do next time.\n\nMicrocopy is also a chance to create a friendly relationship and\nestablish your brand with your audience. Users are less likely to get\nfrustrated if the error message has a personal and human sentiment than\nif it merely says \"ACCESS DENIED\", or \"FORBIDDEN ACTION\".\n\nIn this talk I show how making error message Humble, Human, and Helpful\nis critical to making your users Happy. We''ll laugh at a few bad\nerrors, and learn from the good error messages and microcopy.\n", "duration": 956, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-even-naming-this-talk-is-hard-by-ruthie-bendor.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-even-naming-this-talk-is-hard-by-ruthie-bendor.json index e23820db7..f76549ae8 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-even-naming-this-talk-is-hard-by-ruthie-bendor.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-even-naming-this-talk-is-hard-by-ruthie-bendor.json @@ -1,7 +1,6 @@ { - "abstract": "Writers of software and writers of documentation practice a shared art:\nwe bestow abstractions with names. We know we''ve succeeded when our\nnames illuminate concepts, elicit a-ha moments, and empower users to put\nour product to work. We know we''ve failed when the names we''ve chosen\nconfuse, frustrate, misguide, or offend.\n\nNaming things well matters. Too often, though, good names are hard to\ncome by, and bad names are hard to change.\n\nUsing a lengthy and ever-growing list of Terrible, Horrible, No Good,\nVery Bad names encountered during my career as an engineer, this talk\nwill address: - Why is it so hard to name things well in software? - Why\ndo bad names persist? - What are some heuristics for assessing how good\nor bad a name is? - How has technology hampered efforts to name things\nwell? - How can technology help our efforts to name things well? - How\ncan documentarians and developers work together to name things better?\n", "copyright_text": null, - "description": "", + "description": "Writers of software and writers of documentation practice a shared art:\nwe bestow abstractions with names. We know we''ve succeeded when our\nnames illuminate concepts, elicit a-ha moments, and empower users to put\nour product to work. We know we''ve failed when the names we''ve chosen\nconfuse, frustrate, misguide, or offend.\n\nNaming things well matters. Too often, though, good names are hard to\ncome by, and bad names are hard to change.\n\nUsing a lengthy and ever-growing list of Terrible, Horrible, No Good,\nVery Bad names encountered during my career as an engineer, this talk\nwill address: - Why is it so hard to name things well in software? - Why\ndo bad names persist? - What are some heuristics for assessing how good\nor bad a name is? - How has technology hampered efforts to name things\nwell? - How can technology help our efforts to name things well? - How\ncan documentarians and developers work together to name things better?\n", "duration": 1542, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-everyone-s-a-player-in-a-mid-90s-mud-by-kenzie-woodbridge.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-everyone-s-a-player-in-a-mid-90s-mud-by-kenzie-woodbridge.json index 8bd332105..fc11a6a70 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-everyone-s-a-player-in-a-mid-90s-mud-by-kenzie-woodbridge.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-everyone-s-a-player-in-a-mid-90s-mud-by-kenzie-woodbridge.json @@ -1,7 +1,6 @@ { - "abstract": "*> N*\n\nYou have found a secret room in the castle! You gain 26 xp.\n\nYou enter a large interior space with stone walls and a high stone\nceiling. Torches flicker in wall brackets. A large self-referential\ntapestry hanging on the north wall shows a guild workshop full of happy\nweavers busily weaving the very tapestry in which they are depicted.\nThere are exits to the east, west, and south.\n\n**Linden** , another player, is here. **Gwyrian** , another player, is\nhere.\n\n*> say \"Hi\"*\n\nYou say \"Hi\"\n\nGwyrian says \"Hey! Do you want to explore this area together?\"\n\nLinden attacks you with a critical hit from their sword!\n\nYou are dead!\n\nOther people: sometimes difficult to work with and often impossible to\npredict. In your technical or documentation project, how can you get the\nright people interested and involved? How can you keep those people\nhappily engaged until the work is done? Is there anything you can do to\nprevent griefing\u2026 err, \u201cinterpersonal difficulties\u201d from causing delays?\nAnd why do some people seem to thrive in an environment with poor\ndocumentation and how can you encourage them to participate in\neffectively documenting everything anyway?\n\nIn this talk, I'll explore ways to accomplish these aims, using\nstrategies drawn from \u201cPlayer Type Theory\u201d . For 20 years, this theory\nhas been employed by game designers to encourage stable long-term play\ncommunities in online multiplayer games. These are strategies that I\nhave used successfully in my workplace and they can work for you too.\n", "copyright_text": null, - "description": "", + "description": "*> N*\n\nYou have found a secret room in the castle! You gain 26 xp.\n\nYou enter a large interior space with stone walls and a high stone\nceiling. Torches flicker in wall brackets. A large self-referential\ntapestry hanging on the north wall shows a guild workshop full of happy\nweavers busily weaving the very tapestry in which they are depicted.\nThere are exits to the east, west, and south.\n\n**Linden** , another player, is here. **Gwyrian** , another player, is\nhere.\n\n*> say \"Hi\"*\n\nYou say \"Hi\"\n\nGwyrian says \"Hey! Do you want to explore this area together?\"\n\nLinden attacks you with a critical hit from their sword!\n\nYou are dead!\n\nOther people: sometimes difficult to work with and often impossible to\npredict. In your technical or documentation project, how can you get the\nright people interested and involved? How can you keep those people\nhappily engaged until the work is done? Is there anything you can do to\nprevent griefing\u2026 err, \u201cinterpersonal difficulties\u201d from causing delays?\nAnd why do some people seem to thrive in an environment with poor\ndocumentation and how can you encourage them to participate in\neffectively documenting everything anyway?\n\nIn this talk, I'll explore ways to accomplish these aims, using\nstrategies drawn from \u201cPlayer Type Theory\u201d . For 20 years, this theory\nhas been employed by game designers to encourage stable long-term play\ncommunities in online multiplayer games. These are strategies that I\nhave used successfully in my workplace and they can work for you too.\n", "duration": 1793, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-intelligent-documents-and-the-verifiability-crisis-in-science.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-intelligent-documents-and-the-verifiability-crisis-in-science.json index 87c93ddf4..bb69214a7 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-intelligent-documents-and-the-verifiability-crisis-in-science.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-intelligent-documents-and-the-verifiability-crisis-in-science.json @@ -1,7 +1,6 @@ { - "abstract": "This talk is about the verifiability crisis in science, politics, and\ntechnology, and how methods developed to address verifiablity in\nstatistical publishing can be adapted to other areas such as technical\nwriting.\n\n- In 2015, a group of researchers set out to replicate the results\n obtained in a set of 100 published psychology research papers. It\n turned out that only 29 out of the 100 could be replicated.\n\n- In the 2016 elections, so-called \"fake news\"--fabricated news\n published on venues such as Facebook--influenced many voters in their\n choice of candidates.\n\n- In the field of technical writing, it is not uncommon to discover\n that technical documentation is inaccurate. Although the docs might\n have been accurate when first published, the underlying technology\n evolved rendering the docs obsolete.\n\nAcademic, public-policy, and business decisions are sometimes made after\naccepting published (mis)information at face value. The costs can\nbeconsiderable.\n\nThe information often arrives in the form of an electronic document,\nsuch as a web page or PDF file. To verify the information, someone has\nto \"fact check\" it. But what if the document could, in some sense,\n\"speakfor itself\" and demonstrate the veracity of what it is saying?\n\nIn response to the verifiability crisis in science, statisticians\nhavedeveloped technology to create \"intelligent documents\" that not\nonlyreport the results of a statistical analysis, but can also re-create\ntheanalysis itself.\n", "copyright_text": null, - "description": "", + "description": "This talk is about the verifiability crisis in science, politics, and\ntechnology, and how methods developed to address verifiablity in\nstatistical publishing can be adapted to other areas such as technical\nwriting.\n\n- In 2015, a group of researchers set out to replicate the results\n obtained in a set of 100 published psychology research papers. It\n turned out that only 29 out of the 100 could be replicated.\n\n- In the 2016 elections, so-called \"fake news\"--fabricated news\n published on venues such as Facebook--influenced many voters in their\n choice of candidates.\n\n- In the field of technical writing, it is not uncommon to discover\n that technical documentation is inaccurate. Although the docs might\n have been accurate when first published, the underlying technology\n evolved rendering the docs obsolete.\n\nAcademic, public-policy, and business decisions are sometimes made after\naccepting published (mis)information at face value. The costs can\nbeconsiderable.\n\nThe information often arrives in the form of an electronic document,\nsuch as a web page or PDF file. To verify the information, someone has\nto \"fact check\" it. But what if the document could, in some sense,\n\"speakfor itself\" and demonstrate the veracity of what it is saying?\n\nIn response to the verifiability crisis in science, statisticians\nhavedeveloped technology to create \"intelligent documents\" that not\nonlyreport the results of a statistical analysis, but can also re-create\ntheanalysis itself.\n", "duration": 1676, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-interviewing-and-hiring-technical-writers-by-sam-faktorovich.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-interviewing-and-hiring-technical-writers-by-sam-faktorovich.json index e3f1692ba..45e523138 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-interviewing-and-hiring-technical-writers-by-sam-faktorovich.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-interviewing-and-hiring-technical-writers-by-sam-faktorovich.json @@ -1,7 +1,6 @@ { - "abstract": "My name is Sam and I am the head of technical documentation department\nat Zodiac Interactive.\n\nAt Zodiac we create low-level software (we call it 'middleware') that\nruns inside cable TV set-top boxes. Most cable companies in North\nAmerica use our products; most probably, your set-top box runs at least\nsome code written by Zodiac.\n\nZodiac has R&D departments all over the world; my office is located in\nNovosibirsk, Russia \u2013 right in the center of Siberia (so yes, there is a\nbig probability that your set-top box runs some code that was written in\nthe midst of Siberian taiga)\n\nDocumentation department at our R&D center concentrates only on\narchitectural documentation: our docs explain the design and\narchitectural decisions of our software components to other teams and\nR&D centers all over the world . We don't document user interface, write\nclient knowledge bases, or do UI copy. Our technical writers must be\ntech-savvy enough to understand the architectural peculiarities of\ncomplex multithreaded applications, must be able to read code in C++\nand, above all, must have perfect written English \u2013 Zodiac is an\nAmerican company, and we write all our docs in English, not Russian.\n\nDuring the last 5 years our R&D center went from not having any\ndocumentarians at all to a team of 4 excellent and capable technical\nwriters. We were able to set up effective processes of integrating\ndocumentation in overall development activities and find out good\nmetrics for quality of architectural docs.\n\nDocumentation processes and documentation quality are frequent topics at\nWrite the Docs, so I want to talk about more generic things:\ninterviewing, assessing and hiring technical writers.\n\nMy talk will tackle the following questions:\n\n- How hard is it to find a \"highly technical\" technical writer?\n (remember that our documentarians must read and understand C++ code)\n\n- Is it possible to switch your non-documentarian team members to\n writing documentation full-time? Do developers make good technical\n writers? What about QA engineers? (our answer was no: it's better to\n hire new documentarians than to evolve existing team members into\n technical writers)\n\n- Which one is easier: hiring a technically capable person and teaching\n them to write well, or hiring a person with good writing skills but\n no technical knowledge whatsoever and then training them on technical\n stuff? (we went with the second option)\n\n- Assessing the candidates: what is the perfect pre-interview\n assignment test and is it OK if the typical candidate spends 10-14\n days to complete it? Should your candidates write something that\n resembles your working docs, or some generic texts on complex topics\n are enough? (for example, we ask our candidates to explain SSL\n certificates to their math-savvy, but not-cryptographically-inclined\n uncle: private/public keys, digital signatures, chains of trust and\n so on)\n\n- Interviewing candidates for a technical writer position: are\n interviews necessary at all? Can a good interview outweigh a bad\n assignment test? Can a bad interview spoil the impression after a\n good assignment test? What things should be asked during an\n interview?\n", "copyright_text": null, - "description": "", + "description": "My name is Sam and I am the head of technical documentation department\nat Zodiac Interactive.\n\nAt Zodiac we create low-level software (we call it 'middleware') that\nruns inside cable TV set-top boxes. Most cable companies in North\nAmerica use our products; most probably, your set-top box runs at least\nsome code written by Zodiac.\n\nZodiac has R&D departments all over the world; my office is located in\nNovosibirsk, Russia \u2013 right in the center of Siberia (so yes, there is a\nbig probability that your set-top box runs some code that was written in\nthe midst of Siberian taiga)\n\nDocumentation department at our R&D center concentrates only on\narchitectural documentation: our docs explain the design and\narchitectural decisions of our software components to other teams and\nR&D centers all over the world . We don't document user interface, write\nclient knowledge bases, or do UI copy. Our technical writers must be\ntech-savvy enough to understand the architectural peculiarities of\ncomplex multithreaded applications, must be able to read code in C++\nand, above all, must have perfect written English \u2013 Zodiac is an\nAmerican company, and we write all our docs in English, not Russian.\n\nDuring the last 5 years our R&D center went from not having any\ndocumentarians at all to a team of 4 excellent and capable technical\nwriters. We were able to set up effective processes of integrating\ndocumentation in overall development activities and find out good\nmetrics for quality of architectural docs.\n\nDocumentation processes and documentation quality are frequent topics at\nWrite the Docs, so I want to talk about more generic things:\ninterviewing, assessing and hiring technical writers.\n\nMy talk will tackle the following questions:\n\n- How hard is it to find a \"highly technical\" technical writer?\n (remember that our documentarians must read and understand C++ code)\n\n- Is it possible to switch your non-documentarian team members to\n writing documentation full-time? Do developers make good technical\n writers? What about QA engineers? (our answer was no: it's better to\n hire new documentarians than to evolve existing team members into\n technical writers)\n\n- Which one is easier: hiring a technically capable person and teaching\n them to write well, or hiring a person with good writing skills but\n no technical knowledge whatsoever and then training them on technical\n stuff? (we went with the second option)\n\n- Assessing the candidates: what is the perfect pre-interview\n assignment test and is it OK if the typical candidate spends 10-14\n days to complete it? Should your candidates write something that\n resembles your working docs, or some generic texts on complex topics\n are enough? (for example, we ask our candidates to explain SSL\n certificates to their math-savvy, but not-cryptographically-inclined\n uncle: private/public keys, digital signatures, chains of trust and\n so on)\n\n- Interviewing candidates for a technical writer position: are\n interviews necessary at all? Can a good interview outweigh a bad\n assignment test? Can a bad interview spoil the impression after a\n good assignment test? What things should be asked during an\n interview?\n", "duration": 1480, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-no-community-members-were-harmed-by-lindsay-muscato-ryan-pitts.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-no-community-members-were-harmed-by-lindsay-muscato-ryan-pitts.json index 42c63ff2f..44ae11978 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-no-community-members-were-harmed-by-lindsay-muscato-ryan-pitts.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-no-community-members-were-harmed-by-lindsay-muscato-ryan-pitts.json @@ -1,7 +1,6 @@ { - "abstract": "For developers in newsrooms, whose work supports great writing and\njournalism all day long, writing their own docs often falls by the\nwayside. News deadlines can leave little time for cleanup and\ndocumentation (much less the planning that leads to reusable code). At\nOpenNews, these developers, designers, and data analysts are our\ncommunity, and we designed a series of small events to address that time\ncrunch. We bring people together a few times a year to refine, document,\nand release open-source projects, because a common set of tools means\nmore time spent covering the news, less time on recreating code.\n\nDuring these events, we''ve seen a common set of cultural and technical\nquestions come up before, during, and after projects--but our community\ndidn''t have a common pool of answers.\n\nSo last year, we did something about it. Inspired by collaborative book-\nwriting projects, we put together a community documentation sprint in\nDecember 2016. The goal: to draft a guidebook for releasing newsroom\ncode. Over two intensive days, 11 contributors gathered with us in\nWashington, D.C., and another dozen signed on as remote editors.\nTogether, they captured our community''s best practices for\nopen-sourcing software, specifically in the context of newsrooms and\njournalism. They worked in pairs or small groups, clustered around\nlaptops, collaborating for long stretches of writing. We fed them many\nsnacks.\n\nThe Field Guide to Open Source in the Newsroom launched in February, and\nwe learned a lot as it came together. We''d love to tell you:\n\n- How we recruited and prepared a diverse, expert team of participants\n for a productive event\n\n- How we ran the two-day documentation sprint, with a flexible,\n supportive structure\n\n- How we built in time for followthrough after the event, with plans\n for outreach, adoption and onboarding\n\n- And how we made the whole thing human-friendly\n", "copyright_text": null, - "description": "", + "description": "For developers in newsrooms, whose work supports great writing and\njournalism all day long, writing their own docs often falls by the\nwayside. News deadlines can leave little time for cleanup and\ndocumentation (much less the planning that leads to reusable code). At\nOpenNews, these developers, designers, and data analysts are our\ncommunity, and we designed a series of small events to address that time\ncrunch. We bring people together a few times a year to refine, document,\nand release open-source projects, because a common set of tools means\nmore time spent covering the news, less time on recreating code.\n\nDuring these events, we''ve seen a common set of cultural and technical\nquestions come up before, during, and after projects--but our community\ndidn''t have a common pool of answers.\n\nSo last year, we did something about it. Inspired by collaborative book-\nwriting projects, we put together a community documentation sprint in\nDecember 2016. The goal: to draft a guidebook for releasing newsroom\ncode. Over two intensive days, 11 contributors gathered with us in\nWashington, D.C., and another dozen signed on as remote editors.\nTogether, they captured our community''s best practices for\nopen-sourcing software, specifically in the context of newsrooms and\njournalism. They worked in pairs or small groups, clustered around\nlaptops, collaborating for long stretches of writing. We fed them many\nsnacks.\n\nThe Field Guide to Open Source in the Newsroom launched in February, and\nwe learned a lot as it came together. We''d love to tell you:\n\n- How we recruited and prepared a diverse, expert team of participants\n for a productive event\n\n- How we ran the two-day documentation sprint, with a flexible,\n supportive structure\n\n- How we built in time for followthrough after the event, with plans\n for outreach, adoption and onboarding\n\n- And how we made the whole thing human-friendly\n", "duration": 1581, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-only-interesting-conversations-by-matthew-buttler.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-only-interesting-conversations-by-matthew-buttler.json index b53e98b31..ffd7e3ff3 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-only-interesting-conversations-by-matthew-buttler.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-only-interesting-conversations-by-matthew-buttler.json @@ -1,7 +1,6 @@ { - "abstract": "In this talk I'll discuss the partnership between documentarians and\nsupport and how that relationship can embolden your customers.\n\nDocumentation can make or break a support interaction. Your average\ncustomer or client isn't interested in a lot of work to use your\nproduct. They need to know how to make your product do \"the thing\"\nwithout, say, opening a Rails console, or doing some other godforsaken\nprogramming trick that you know.\n\nYou might not know this but your support team has a life of its own that\nyou haven't seen. Having been a documentarian in the context of a\nsupport team, I have some pretty interesting things to talk about how\nyou can weave relationships to make everyone's life better, all the way\nup the food chain.\n\nI'll talk about how working in partnership with your support team can\nnot only focus your docs to the points that matter, but let you see how\noperating as connective tissue between departments makes everyone's life\neasier.\n", "copyright_text": null, - "description": "", + "description": "In this talk I'll discuss the partnership between documentarians and\nsupport and how that relationship can embolden your customers.\n\nDocumentation can make or break a support interaction. Your average\ncustomer or client isn't interested in a lot of work to use your\nproduct. They need to know how to make your product do \"the thing\"\nwithout, say, opening a Rails console, or doing some other godforsaken\nprogramming trick that you know.\n\nYou might not know this but your support team has a life of its own that\nyou haven't seen. Having been a documentarian in the context of a\nsupport team, I have some pretty interesting things to talk about how\nyou can weave relationships to make everyone's life better, all the way\nup the food chain.\n\nI'll talk about how working in partnership with your support team can\nnot only focus your docs to the points that matter, but let you see how\noperating as connective tissue between departments makes everyone's life\neasier.\n", "duration": 1264, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-start-with-the-tasks-not-the-endpoints-by-sarah-hersh.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-start-with-the-tasks-not-the-endpoints-by-sarah-hersh.json index 369242423..57798184c 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-start-with-the-tasks-not-the-endpoints-by-sarah-hersh.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-start-with-the-tasks-not-the-endpoints-by-sarah-hersh.json @@ -1,7 +1,6 @@ { - "abstract": "Last spring, as I approached reworking the information architecture of\nthe NPR One Developer Center, I started by interviewing several of our\npartner developers to find out what pain points they encountered when\ndeveloping on our platform.\n\nOverwhelmingly, the responses included complaints about confusing site\nnavigation and frustration around having to search multiple pages to\nstring together the necessary information to implement features. After\nconsidering this feedback, we redesigned the documentation site to focus\non information needed to complete a desired task, and while we still\nprovide endpoint reference documentation, my focus now is to start from\nthinking about what a developer is trying to accomplish, rather than\nwhat data an endpoint is capable of providing. Essentially, the focus of\nthe docs shifted away from what the API can do, towards what \u201cI\u201d, as the\ndeveloper, can do with this API.\n\nTaking a task-oriented approach allowed us to reorganize and revise our\ncontent in a way that has significantly shortened our onboarding process\nfor partner developers, shortening the app verification process and\ntime-to- market, and most importantly allows us to better collaborate\nwith our partners to develop exciting new experiences for NPR listeners.\nFor those who work on documenting hypermedia APIs, this can be a\nparticularly useful approach, since these services tend to have fewer\nspecific endpoints, and the documentation needs to focus much more on\nhow the client can successfully navigate links to accomplish the desired\ntask. In this 30-minute talk, I' ll discuss how you can successfully\nintegrate this approach to your workflow when considering everything\nfrom overall information architecture, to deciding which content assets\nto prioritize, to refining the tone used throughout your developer\ncommunications.\n", "copyright_text": null, - "description": "", + "description": "Last spring, as I approached reworking the information architecture of\nthe NPR One Developer Center, I started by interviewing several of our\npartner developers to find out what pain points they encountered when\ndeveloping on our platform.\n\nOverwhelmingly, the responses included complaints about confusing site\nnavigation and frustration around having to search multiple pages to\nstring together the necessary information to implement features. After\nconsidering this feedback, we redesigned the documentation site to focus\non information needed to complete a desired task, and while we still\nprovide endpoint reference documentation, my focus now is to start from\nthinking about what a developer is trying to accomplish, rather than\nwhat data an endpoint is capable of providing. Essentially, the focus of\nthe docs shifted away from what the API can do, towards what \u201cI\u201d, as the\ndeveloper, can do with this API.\n\nTaking a task-oriented approach allowed us to reorganize and revise our\ncontent in a way that has significantly shortened our onboarding process\nfor partner developers, shortening the app verification process and\ntime-to- market, and most importantly allows us to better collaborate\nwith our partners to develop exciting new experiences for NPR listeners.\nFor those who work on documenting hypermedia APIs, this can be a\nparticularly useful approach, since these services tend to have fewer\nspecific endpoints, and the documentation needs to focus much more on\nhow the client can successfully navigate links to accomplish the desired\ntask. In this 30-minute talk, I' ll discuss how you can successfully\nintegrate this approach to your workflow when considering everything\nfrom overall information architecture, to deciding which content assets\nto prioritize, to refining the tone used throughout your developer\ncommunications.\n", "duration": 1676, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-testing-it-s-not-just-for-code-anymore-by-lyzi-diamond.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-testing-it-s-not-just-for-code-anymore-by-lyzi-diamond.json index dcd72091b..a2ec5fcdf 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-testing-it-s-not-just-for-code-anymore-by-lyzi-diamond.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-testing-it-s-not-just-for-code-anymore-by-lyzi-diamond.json @@ -1,7 +1,6 @@ { - "abstract": "We call ourselves technical writers, but many of us spend more time\nediting the work of others than writing ourselves. When you have a large\nteam or a large product (or both!), the cooks in the documentation\nkitchen come from all parts of the company: marketing, product,\nengineering, sales, and more. This adds a significant burden on you and\nyour team to make sure the content they produce is accurate, fits within\nyour style guide, uses the correct tone, and doesn''t add additional\nconfusion.\n\nAt Mapbox, we have both a large team and a complex product, which means\nmany different writers with individual writing styles and varying depth\nof knowledge of the product. To keep our work accurate and unified under\na common voice while avoiding breaking our necks with editing, we\nimplemented an automated content testing system (fully open source!) to\ndo some of the work for us. Automated tests have helped us embed quality\nwriting and editing into the development process as much as code testing\ndoes. \"It''s not finished until it''s documented\" is more than just a\nhappy thought -- it''s now an immovable part of our workflow.\n\nIn this talk, I will discuss the reasons you might want to implement an\nautomated testing system in your organization, examples of how it''s\nbeen beneficial, the story of how we set up our system, and a brief\noverview of the tools that exist for doing this work. I''ll also cover\nthe ways that automated tests can sometimes make funny mistakes and how\nwe found the balance between making tests too precise and not precise\nenough. For those who are interested in implementing right away, I will\nalso provide a comprehensive list of resources for getting started.\n", "copyright_text": null, - "description": "", + "description": "We call ourselves technical writers, but many of us spend more time\nediting the work of others than writing ourselves. When you have a large\nteam or a large product (or both!), the cooks in the documentation\nkitchen come from all parts of the company: marketing, product,\nengineering, sales, and more. This adds a significant burden on you and\nyour team to make sure the content they produce is accurate, fits within\nyour style guide, uses the correct tone, and doesn''t add additional\nconfusion.\n\nAt Mapbox, we have both a large team and a complex product, which means\nmany different writers with individual writing styles and varying depth\nof knowledge of the product. To keep our work accurate and unified under\na common voice while avoiding breaking our necks with editing, we\nimplemented an automated content testing system (fully open source!) to\ndo some of the work for us. Automated tests have helped us embed quality\nwriting and editing into the development process as much as code testing\ndoes. \"It''s not finished until it''s documented\" is more than just a\nhappy thought -- it''s now an immovable part of our workflow.\n\nIn this talk, I will discuss the reasons you might want to implement an\nautomated testing system in your organization, examples of how it''s\nbeen beneficial, the story of how we set up our system, and a brief\noverview of the tools that exist for doing this work. I''ll also cover\nthe ways that automated tests can sometimes make funny mistakes and how\nwe found the balance between making tests too precise and not precise\nenough. For those who are interested in implementing right away, I will\nalso provide a comprehensive list of resources for getting started.\n", "duration": 1487, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-the-wisdom-of-crowds-by-ingrid-towey.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-the-wisdom-of-crowds-by-ingrid-towey.json index 8d4474739..6ae471186 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-the-wisdom-of-crowds-by-ingrid-towey.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-the-wisdom-of-crowds-by-ingrid-towey.json @@ -1,7 +1,6 @@ { - "abstract": "The Wisdom of Crowds:Crowdsourcing Minimalism in an Open Organization by\nIngrid Towey, Brice Fallon-Freeman, and Aneta Petrov\u00e1\n\nWhat does choosing flavors of LaCroix sparkling water for the Red Hat\nbreakroom have to do with improving technical documentation? At Red Hat,\neverything.\n\nYou see, when we wanted to make a culture shift in our approach to\ndocumentation, we couldn't legislate the change from the top down.\nManagers and experts just don't have that kind of authority at Red Hat.\nChanging the way we write has had to be a grassroots, bottom-up effort.\nJust like we all get to vote on which flavors of sparkling water and\nother beverages are stocked in our fridge, writers, editors, content\nstrategists, and managers ALL have a say in our latest writing trends.\nAt Red Hat, we have an open culture where people expect to have a voice\nin decisions and aren't afraid to speak their minds. This open culture\naffects every aspect of our working lives.\n\nWhat Did We Want to Change? We wanted to introduce our teams to\nminimalist writing. But first we had to convince people that minimalism\nisn't just about shorter sentences and less fluffy documentation.\nMinimalist writing means that you focus like a laser on just what your\ncustomers need at the moment. It's harder than it sounds.\n\nHow Did We Do It?First, we formed an international team that could\ninfluence writers across all our geographical regions (geos). Brice\nFallon-Freeman (from Australia), Aneta Petrov\u00e1 (from the Czech\nRepublic), and I (from the US) became this team and brainstormed ways to\nintroduce these concepts to our departments.\n\nAneta and Brice came up with the idea of crowdsourcing minimalist\nwriting critiques, and all three of us tried the concept in our\ndifferent geos. We got volunteers to join our groups, and then we got\nmore volunteers who were willing to have their content critiqued. This\n\u201ccrowd\u201d of writers and editors then worked together to give meaningful\nfeedback to the people who had been brave enough to volunteer their\ncontent.\n\nThe beauty of this model is that it gives experienced writers a way to\nteach more junior writers without the process being apparent. No one has\nto admit to being ignorant. Inexperienced writers get to learn about\nminimalism by watching other people apply it to real content and not in\nsome kind of fake training situation.\n\nThis talk will discuss our strategies and methods in more detail and\nshow examples of content before and after crowdsourced minimalism.\n", "copyright_text": null, - "description": "", + "description": "The Wisdom of Crowds:Crowdsourcing Minimalism in an Open Organization by\nIngrid Towey, Brice Fallon-Freeman, and Aneta Petrov\u00e1\n\nWhat does choosing flavors of LaCroix sparkling water for the Red Hat\nbreakroom have to do with improving technical documentation? At Red Hat,\neverything.\n\nYou see, when we wanted to make a culture shift in our approach to\ndocumentation, we couldn't legislate the change from the top down.\nManagers and experts just don't have that kind of authority at Red Hat.\nChanging the way we write has had to be a grassroots, bottom-up effort.\nJust like we all get to vote on which flavors of sparkling water and\nother beverages are stocked in our fridge, writers, editors, content\nstrategists, and managers ALL have a say in our latest writing trends.\nAt Red Hat, we have an open culture where people expect to have a voice\nin decisions and aren't afraid to speak their minds. This open culture\naffects every aspect of our working lives.\n\nWhat Did We Want to Change? We wanted to introduce our teams to\nminimalist writing. But first we had to convince people that minimalism\nisn't just about shorter sentences and less fluffy documentation.\nMinimalist writing means that you focus like a laser on just what your\ncustomers need at the moment. It's harder than it sounds.\n\nHow Did We Do It?First, we formed an international team that could\ninfluence writers across all our geographical regions (geos). Brice\nFallon-Freeman (from Australia), Aneta Petrov\u00e1 (from the Czech\nRepublic), and I (from the US) became this team and brainstormed ways to\nintroduce these concepts to our departments.\n\nAneta and Brice came up with the idea of crowdsourcing minimalist\nwriting critiques, and all three of us tried the concept in our\ndifferent geos. We got volunteers to join our groups, and then we got\nmore volunteers who were willing to have their content critiqued. This\n\u201ccrowd\u201d of writers and editors then worked together to give meaningful\nfeedback to the people who had been brave enough to volunteer their\ncontent.\n\nThe beauty of this model is that it gives experienced writers a way to\nteach more junior writers without the process being apparent. No one has\nto admit to being ignorant. Inexperienced writers get to learn about\nminimalism by watching other people apply it to real content and not in\nsome kind of fake training situation.\n\nThis talk will discuss our strategies and methods in more detail and\nshow examples of content before and after crowdsourced minimalism.\n", "duration": 2004, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-treating-documentation-like-code-a-practical-account-by-jodie-putrino.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-treating-documentation-like-code-a-practical-account-by-jodie-putrino.json index 5250ecdd9..b327e7cbf 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-treating-documentation-like-code-a-practical-account-by-jodie-putrino.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-treating-documentation-like-code-a-practical-account-by-jodie-putrino.json @@ -1,7 +1,6 @@ { - "abstract": "Are you interested in developing docs like code? Are you frustrated by\nthe lack of available information as to what that really means and how\nexactly you're supposed to do it? Welcome to the club!\n\n\"Treating documentation like code\" is somewhat of a buzzword bingo term\nthese days. You can find any number of blog posts, presentations, and\narticles online expounding on the theory and merits of the idea. When I\nwas presented with an opportunity to truly integrate documentation into\nthe agile development process almost 2 years ago, I couldn't find any\ninformation that could teach me how to treat docs like code. Since then,\nI've worked with a team of passionate software engineers to bring a long\nlist of 'awesome-future' ideas for treating documentation like code into\npractice. In this presentation, I'll lay out how we create, test, build,\nand publish our documentation using agile methodologies, so others\nstarting down the same road have a path to follow.\n\nIn the beginning, we had a great idea - documentation should be\ndeveloped, tested, and built just like the products we make. The\nkeystone of this grand vision was the idea that docs live in the same\nrepositories as the code, use the same development tools and code review\nprocesses, and follow a continuous delivery model. I'll go over the\ntools we chose to write, build, and test the docs; the responsibilities\nof the software engineers and technical writer, respectively, for\ncreating and maintaining content; the docs information architecture we\ndeveloped; how we incorporated syntax and grammar checks into code\ntesting; and how we build and deploy our documentation automatically.\n", "copyright_text": null, - "description": "", + "description": "Are you interested in developing docs like code? Are you frustrated by\nthe lack of available information as to what that really means and how\nexactly you're supposed to do it? Welcome to the club!\n\n\"Treating documentation like code\" is somewhat of a buzzword bingo term\nthese days. You can find any number of blog posts, presentations, and\narticles online expounding on the theory and merits of the idea. When I\nwas presented with an opportunity to truly integrate documentation into\nthe agile development process almost 2 years ago, I couldn't find any\ninformation that could teach me how to treat docs like code. Since then,\nI've worked with a team of passionate software engineers to bring a long\nlist of 'awesome-future' ideas for treating documentation like code into\npractice. In this presentation, I'll lay out how we create, test, build,\nand publish our documentation using agile methodologies, so others\nstarting down the same road have a path to follow.\n\nIn the beginning, we had a great idea - documentation should be\ndeveloped, tested, and built just like the products we make. The\nkeystone of this grand vision was the idea that docs live in the same\nrepositories as the code, use the same development tools and code review\nprocesses, and follow a continuous delivery model. I'll go over the\ntools we chose to write, build, and test the docs; the responsibilities\nof the software engineers and technical writer, respectively, for\ncreating and maintaining content; the docs information architecture we\ndeveloped; how we incorporated syntax and grammar checks into code\ntesting; and how we build and deploy our documentation automatically.\n", "duration": 1408, "language": "eng", "recorded": "2017-05-15", diff --git a/writethedocs-na-2017/videos/write-the-docs-portland-2017-you-have-already-succeeded-by-christy-lutz.json b/writethedocs-na-2017/videos/write-the-docs-portland-2017-you-have-already-succeeded-by-christy-lutz.json index 87af21ce7..8c3f74e27 100644 --- a/writethedocs-na-2017/videos/write-the-docs-portland-2017-you-have-already-succeeded-by-christy-lutz.json +++ b/writethedocs-na-2017/videos/write-the-docs-portland-2017-you-have-already-succeeded-by-christy-lutz.json @@ -1,7 +1,6 @@ { - "abstract": "Getting feedback on your work is a necessary part of any project, and it\nmakes your output stronger and more diverse. But it can be hard when\nyour work is being evaluated. Sometimes, it feels like your reviewers\nhave a deep and abiding interest in pain. You'll never succeed! You may\nas well die here! Well, you have already succeeded just by asking for\nfeedback. Together, we'll discuss how to build up your tolerance for\ntaking that feedback.\n\nFeedback became so much easier for me when I learned design critique\nguidelines from a co-worker and UX Designer. Design critique guidelines\nare a set of rules and practices that can make getting and giving\nfeedback easier. This presentation passes along the strategies I learned\nso you can implement design critique guidelines into your review process\nand make feedback painless.\n", "copyright_text": null, - "description": "", + "description": "Getting feedback on your work is a necessary part of any project, and it\nmakes your output stronger and more diverse. But it can be hard when\nyour work is being evaluated. Sometimes, it feels like your reviewers\nhave a deep and abiding interest in pain. You'll never succeed! You may\nas well die here! Well, you have already succeeded just by asking for\nfeedback. Together, we'll discuss how to build up your tolerance for\ntaking that feedback.\n\nFeedback became so much easier for me when I learned design critique\nguidelines from a co-worker and UX Designer. Design critique guidelines\nare a set of rules and practices that can make getting and giving\nfeedback easier. This presentation passes along the strategies I learned\nso you can implement design critique guidelines into your review process\nand make feedback painless.\n", "duration": 1273, "language": "eng", "recorded": "2017-05-15", From 8c64335bc30fa64423cb9c2ab7323a503ac2ae45 Mon Sep 17 00:00:00 2001 From: Jon Banafato Date: Mon, 29 Jul 2024 16:10:13 -0400 Subject: [PATCH 5/7] Write The Docs EU 2017: move talk abstracts into description field --- ...anager-s-guide-to-crowdsourcing-the-docs-by-becky-todd.json | 3 +-- ...017-aw-snap-the-docs-they-are-a-changin-by-kate-wilcox.json | 3 +-- ...itique-guidelines-make-feedback-easier-by-christy-lutz.json | 3 +-- ...s-prague-2017-documentation-beyond-words-by-chris-ward.json | 3 +-- ...-documenting-your-softwares-last-days-by-daniel-d-beck.json | 3 +-- ...ue-2017-even-naming-this-talk-is-hard-by-ruthie-bendor.json | 3 +-- ...s-prague-2017-hi-my-name-is-readme-by-raphael-pierzina.json | 3 +-- ...ays-after-one-year-in-documentation-by-meike-chabowski.json | 3 +-- ...essions-inclusive-language-by-cory-williamson-cardneau.json | 3 +-- ...ments-that-you-didn-t-know-were-there-by-lesia-zasadna.json | 3 +-- ...ue-2017-tech-writers-without-borders-by-stuart-culshaw.json | 3 +-- ...ue-2017-telling-a-great-story-on-github-by-lauri-apple.json | 3 +-- ...y-and-sensible-api-docs-with-graphql-by-garen-torikian.json | 3 +-- ...obody-tells-you-about-documentation-by-daniele-procida.json | 3 +-- ...s-prague-2017-writing-a-book-in-2017-by-thomas-parisot.json | 3 +-- ...ting-great-getting-started-documentation-by-tim-rogers.json | 3 +-- 16 files changed, 16 insertions(+), 32 deletions(-) diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-a-content-manager-s-guide-to-crowdsourcing-the-docs-by-becky-todd.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-a-content-manager-s-guide-to-crowdsourcing-the-docs-by-becky-todd.json index 9c6adde56..75e1be898 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-a-content-manager-s-guide-to-crowdsourcing-the-docs-by-becky-todd.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-a-content-manager-s-guide-to-crowdsourcing-the-docs-by-becky-todd.json @@ -1,7 +1,6 @@ { - "abstract": "Crowdsourcing is an increasingly attractive practice that is being used\nto develop documentation. When well designed, this approach increases\ndocumentation velocity and reduces bottlenecks. However, there are (at\nleast) two huge challenges:\n\n- Keeping documentation quality high\n\n- Ensuring that content gets developed in line with the products and\n services it supports\n\nWhile no doc set will ever be perfect, there is hope for overcoming\nthese challenges. In this talk, I'll share lessons learned from working\nthrough these challenges at companies of various sizes. We'll walk\nthrough content management best practices, including:\n\n- Setting occasional authors up for success\n\n- Building an effective writing toolkit\n\n- Defining content management strategies for globally distributed teams\n", "copyright_text": null, - "description": "", + "description": "Crowdsourcing is an increasingly attractive practice that is being used\nto develop documentation. When well designed, this approach increases\ndocumentation velocity and reduces bottlenecks. However, there are (at\nleast) two huge challenges:\n\n- Keeping documentation quality high\n\n- Ensuring that content gets developed in line with the products and\n services it supports\n\nWhile no doc set will ever be perfect, there is hope for overcoming\nthese challenges. In this talk, I'll share lessons learned from working\nthrough these challenges at companies of various sizes. We'll walk\nthrough content management best practices, including:\n\n- Setting occasional authors up for success\n\n- Building an effective writing toolkit\n\n- Defining content management strategies for globally distributed teams\n", "duration": 1590, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-aw-snap-the-docs-they-are-a-changin-by-kate-wilcox.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-aw-snap-the-docs-they-are-a-changin-by-kate-wilcox.json index 2d45aca0a..820e52175 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-aw-snap-the-docs-they-are-a-changin-by-kate-wilcox.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-aw-snap-the-docs-they-are-a-changin-by-kate-wilcox.json @@ -1,7 +1,6 @@ { - "abstract": "This presentation explores the evolution of language in technical\ndocumentation.\n\nThe reign of the long-form narrative in tech docs is long gone. Nobody\nwants to read a 600 page user manual cover to cover before using an\napplication or API. Users crave bite-size chunks of information, and\nthey want them exactly at the point of need. They want just enough\ninformation to complete their task and not one conjunction more. In\nother words, users want high-calorie nutrient-dense documentation, and\nthey want it fast.\n\nTo satisfy users, we documentarians embrace minimalism and topic-based\narchitectures such as DITA. We organize content by type: task, concept,\nreference, etc. We use active voice. We keep sentences short. And\nconsciously or not, we\u2019ve begun to challenge time-honored tech writing\ntraditions, such as prohibitions on future tense, contractions, idioms,\nand colloquialisms \u2013 at least in American English documentation.\n\nWhat\u2019s more, it\u2019s no longer enough for docs to be technically accurate.\nThey must also use contemporary themes familiar to users and, whenever\npossible, humor. Exhibit one is this Google Chrome error:\n\n\u201cAw Snap! Something went wrong while displaying this webpage.\u201d\n\nAnd the folks at ReadMe.io used this line to describe a Delete button in\ntheir interface (from the 2007 film, Juno):\n\n\u201cThis is one doodle that can\u2019t be undid, homeskillet.\u201d\n\nWithout question, the language we use in technical documentation is\nchanging. Contractions, idioms, and colloquialisms, which were once\nbanned as potentially confusing to translators, are now commonplace, and\nwe use them to make our docs sound friendlier. Jargon abounds, the word\n\u201cplease\u201d is no longer taboo, and exclamation points are not only\nallowed, they\u2019re encouraged! They show enthusiasm for the subject!!\n\nIn this presentation, we\u2019ll mine the docosphere for current trends,\ninnovations, and answers to these questions: \u2022 How has the language in\ntech docs evolved over the past decade, and where is it headed? \u2022 What\nare the minimum daily requirements for language in this brave new world:\nCorrect grammar, complete sentences, parallel construction, proper word\nchoice, clarity, brevity? \u2022 What is the role of humor in tech docs? \u2022 Is\nit OK for tech docs to use colloquialisms, idioms, contractions, and\neven emojis? \u2022 What are the implications of this evolution on\nlocalization?\n", "copyright_text": null, - "description": "", + "description": "This presentation explores the evolution of language in technical\ndocumentation.\n\nThe reign of the long-form narrative in tech docs is long gone. Nobody\nwants to read a 600 page user manual cover to cover before using an\napplication or API. Users crave bite-size chunks of information, and\nthey want them exactly at the point of need. They want just enough\ninformation to complete their task and not one conjunction more. In\nother words, users want high-calorie nutrient-dense documentation, and\nthey want it fast.\n\nTo satisfy users, we documentarians embrace minimalism and topic-based\narchitectures such as DITA. We organize content by type: task, concept,\nreference, etc. We use active voice. We keep sentences short. And\nconsciously or not, we\u2019ve begun to challenge time-honored tech writing\ntraditions, such as prohibitions on future tense, contractions, idioms,\nand colloquialisms \u2013 at least in American English documentation.\n\nWhat\u2019s more, it\u2019s no longer enough for docs to be technically accurate.\nThey must also use contemporary themes familiar to users and, whenever\npossible, humor. Exhibit one is this Google Chrome error:\n\n\u201cAw Snap! Something went wrong while displaying this webpage.\u201d\n\nAnd the folks at ReadMe.io used this line to describe a Delete button in\ntheir interface (from the 2007 film, Juno):\n\n\u201cThis is one doodle that can\u2019t be undid, homeskillet.\u201d\n\nWithout question, the language we use in technical documentation is\nchanging. Contractions, idioms, and colloquialisms, which were once\nbanned as potentially confusing to translators, are now commonplace, and\nwe use them to make our docs sound friendlier. Jargon abounds, the word\n\u201cplease\u201d is no longer taboo, and exclamation points are not only\nallowed, they\u2019re encouraged! They show enthusiasm for the subject!!\n\nIn this presentation, we\u2019ll mine the docosphere for current trends,\ninnovations, and answers to these questions: \u2022 How has the language in\ntech docs evolved over the past decade, and where is it headed? \u2022 What\nare the minimum daily requirements for language in this brave new world:\nCorrect grammar, complete sentences, parallel construction, proper word\nchoice, clarity, brevity? \u2022 What is the role of humor in tech docs? \u2022 Is\nit OK for tech docs to use colloquialisms, idioms, contractions, and\neven emojis? \u2022 What are the implications of this evolution on\nlocalization?\n", "duration": 1816, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-design-critique-guidelines-make-feedback-easier-by-christy-lutz.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-design-critique-guidelines-make-feedback-easier-by-christy-lutz.json index 49a330035..5bcc93211 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-design-critique-guidelines-make-feedback-easier-by-christy-lutz.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-design-critique-guidelines-make-feedback-easier-by-christy-lutz.json @@ -1,7 +1,6 @@ { - "abstract": "Getting feedback on your work is a necessary part of any project, and it\nmakes your output stronger and more diverse. But it can be hard when\nyour work is being evaluated. Sometimes, it feels like your reviewers\nhave a deep and abiding interest in pain. You\u2019ll never succeed! Well,\nyou have already succeeded just by asking for feedback. Together, we\u2019ll\ndiscuss how to build up your tolerance for taking that feedback.\n\nFeedback became so much easier for me when I learned design critique\nguidelines from a co-worker and UX Designer. Design critique guidelines\nare a set of rules and practices that can make getting and giving\nfeedback easier. After presenting this speech at the Write the Docs\nPortland 2017 conference, I received a ton of great feedback on it. Now,\nI have even more strategies to share so that you can implement design\ncritique guidelines into your own review process to make feedback\npainless.\n", "copyright_text": null, - "description": "", + "description": "Getting feedback on your work is a necessary part of any project, and it\nmakes your output stronger and more diverse. But it can be hard when\nyour work is being evaluated. Sometimes, it feels like your reviewers\nhave a deep and abiding interest in pain. You\u2019ll never succeed! Well,\nyou have already succeeded just by asking for feedback. Together, we\u2019ll\ndiscuss how to build up your tolerance for taking that feedback.\n\nFeedback became so much easier for me when I learned design critique\nguidelines from a co-worker and UX Designer. Design critique guidelines\nare a set of rules and practices that can make getting and giving\nfeedback easier. After presenting this speech at the Write the Docs\nPortland 2017 conference, I received a ton of great feedback on it. Now,\nI have even more strategies to share so that you can implement design\ncritique guidelines into your own review process to make feedback\npainless.\n", "duration": 1396, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-documentation-beyond-words-by-chris-ward.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-documentation-beyond-words-by-chris-ward.json index a5caf11f3..459a7bba4 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-documentation-beyond-words-by-chris-ward.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-documentation-beyond-words-by-chris-ward.json @@ -1,7 +1,6 @@ { - "abstract": "In this presentation I will explore other ways to communicate concepts\nbeyond words to show that documentation needn't just be about technical\nwriting.\n\nIn the first part of the presentation I will briefly cover theories and\nprinciples behind forms of communication and what documentarians can\nlearn from them. Topics such as:\n\n- Portraying meaning in images: Iconography, maps, manuals\n\n- Non-verbal conversation: Body language, ways of speaking\n\n- Fidelity: Sketch notes, simplicity, style\n\nDuring each of these topics I will present in the style of the topic, so\nexpect something a little different.\n\nIn the second practical part of the presentation I will take elements of\nthe theory and applying them practically. I will start by looking at\nscreenshots and diagrams. When and how to use them, what they should\nshow, and how to manage them.\n\nThen I'll cover taking screenshots to the next level with animated gifs\nand screen recordings that show clear user flows and expected results.\n\nFinally in this part of the presentation I will cover interactive\ndocumentation, and the options for allowing readers to directly\nmanipulate and experiment with documentation and directly see inputs and\noutputs.\n\nIn summary, our work typically appears on one of the most dynamic\nplatforms (the web) that has ever existed, let's all do more with it!\n", "copyright_text": null, - "description": "", + "description": "In this presentation I will explore other ways to communicate concepts\nbeyond words to show that documentation needn't just be about technical\nwriting.\n\nIn the first part of the presentation I will briefly cover theories and\nprinciples behind forms of communication and what documentarians can\nlearn from them. Topics such as:\n\n- Portraying meaning in images: Iconography, maps, manuals\n\n- Non-verbal conversation: Body language, ways of speaking\n\n- Fidelity: Sketch notes, simplicity, style\n\nDuring each of these topics I will present in the style of the topic, so\nexpect something a little different.\n\nIn the second practical part of the presentation I will take elements of\nthe theory and applying them practically. I will start by looking at\nscreenshots and diagrams. When and how to use them, what they should\nshow, and how to manage them.\n\nThen I'll cover taking screenshots to the next level with animated gifs\nand screen recordings that show clear user flows and expected results.\n\nFinally in this part of the presentation I will cover interactive\ndocumentation, and the options for allowing readers to directly\nmanipulate and experiment with documentation and directly see inputs and\noutputs.\n\nIn summary, our work typically appears on one of the most dynamic\nplatforms (the web) that has ever existed, let's all do more with it!\n", "duration": 1046, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-documenting-your-softwares-last-days-by-daniel-d-beck.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-documenting-your-softwares-last-days-by-daniel-d-beck.json index e98ef4af3..211f2a091 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-documenting-your-softwares-last-days-by-daniel-d-beck.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-documenting-your-softwares-last-days-by-daniel-d-beck.json @@ -1,7 +1,6 @@ { - "abstract": "It could happen to you: your project is canceled, your team is\n\u201creorganized\u201d, or your company is closing its doors. Some or all of your\nsoftware, service, or API may not be long for this world. What will you\nsay to the people using your software? In this talk, you\u2019ll learn how to\navoid a communications disaster when it\u2019s time to break bad news to your\nusers.\n\nWhether you\u2019re deprecating significant features or shutting down\nentirely, you still have a chance to make life better\u2014or at least a\nlittle less worse\u2014for the people who have come to rely on your work. In\nthis talk, you\u2019ll learn how to:\n\n- plan your shutdown communications to make sure no users get left\n behind\n\n- let your users down easy with the appropriate voice, tone, and\n content\n\n- cope with a stressful situation\n\nFrom your initial announcement to your service\u2019s last day, you\u2019ll learn\nhow to say goodbye in a way that\u2019s good for you and your\nsoon-to-be-former users.\n", "copyright_text": null, - "description": "", + "description": "It could happen to you: your project is canceled, your team is\n\u201creorganized\u201d, or your company is closing its doors. Some or all of your\nsoftware, service, or API may not be long for this world. What will you\nsay to the people using your software? In this talk, you\u2019ll learn how to\navoid a communications disaster when it\u2019s time to break bad news to your\nusers.\n\nWhether you\u2019re deprecating significant features or shutting down\nentirely, you still have a chance to make life better\u2014or at least a\nlittle less worse\u2014for the people who have come to rely on your work. In\nthis talk, you\u2019ll learn how to:\n\n- plan your shutdown communications to make sure no users get left\n behind\n\n- let your users down easy with the appropriate voice, tone, and\n content\n\n- cope with a stressful situation\n\nFrom your initial announcement to your service\u2019s last day, you\u2019ll learn\nhow to say goodbye in a way that\u2019s good for you and your\nsoon-to-be-former users.\n", "duration": 1396, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-even-naming-this-talk-is-hard-by-ruthie-bendor.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-even-naming-this-talk-is-hard-by-ruthie-bendor.json index e7a6b7f97..87c65782c 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-even-naming-this-talk-is-hard-by-ruthie-bendor.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-even-naming-this-talk-is-hard-by-ruthie-bendor.json @@ -1,7 +1,6 @@ { - "abstract": "Writers of software and writers of documentation practice a shared art:\nwe bestow abstractions with names. We know weve succeeded when our names\nilluminate concepts, elicit a-ha moments, and empower users to put our\nproduct to work. We know we've failed when the names we've chosen\nconfuse, frustrate, misguide, or offend.\n\nNaming things well matters. Too often, though, good names are hard to\ncome by, and bad names are hard to change.\n\nUsing a lengthy and ever-growing list of Terrible, Horrible, No Good,\nVery Bad names encountered during my career as an engineer, this talk\nwill address:\n\n- Why is it so hard to name things well in software?\n\n- Why do bad names persist?\n\n- What are some heuristics for assessing how good or bad a name is?\n\n- How has technology hampered efforts to name things well?\n\n- How can technology help our efforts to name things well?\n\n- How can documentarians and developers work together to name things\n better?\n", "copyright_text": null, - "description": "", + "description": "Writers of software and writers of documentation practice a shared art:\nwe bestow abstractions with names. We know weve succeeded when our names\nilluminate concepts, elicit a-ha moments, and empower users to put our\nproduct to work. We know we've failed when the names we've chosen\nconfuse, frustrate, misguide, or offend.\n\nNaming things well matters. Too often, though, good names are hard to\ncome by, and bad names are hard to change.\n\nUsing a lengthy and ever-growing list of Terrible, Horrible, No Good,\nVery Bad names encountered during my career as an engineer, this talk\nwill address:\n\n- Why is it so hard to name things well in software?\n\n- Why do bad names persist?\n\n- What are some heuristics for assessing how good or bad a name is?\n\n- How has technology hampered efforts to name things well?\n\n- How can technology help our efforts to name things well?\n\n- How can documentarians and developers work together to name things\n better?\n", "duration": 1587, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-hi-my-name-is-readme-by-raphael-pierzina.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-hi-my-name-is-readme-by-raphael-pierzina.json index 02506bf07..6800610ac 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-hi-my-name-is-readme-by-raphael-pierzina.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-hi-my-name-is-readme-by-raphael-pierzina.json @@ -1,7 +1,6 @@ { - "abstract": "When starting a new project, developers, myself included, usually get\nright into hacking things, like tinkering with libraries, that we would\nlike to learn or solving a particular problem as quickly a possible.\nOccasionally we also decide to publish the resulting project to a\nsoftware repository such as PyPI for Python or NPM for Node.js etc., so\nthat others can use our nifty code, submit a pull request and maybe even\nform a community around the project.\n\nAs the creator, you might be lucky and someone will find your project on\nthe front-page of GitHub or maybe eben Hacker News or Reddit. What\nhappens next is on you really. But what does that mean?\n\nBefore jumping right to the command line and installing your package,\nthose who are interested usually try to find out what problems the\nproject is solving and how it can help them with their own. That's what\nyour README file is for - it's most likely the first thing potential\nusers read, that you control.\n\nA good README briefly and concisely explains what your software does,\nhow it can be installed and what API it exposes. You also want to\nprovide information on the requirements, the license it uses and how the\nproject is managed. Who are you? How to get in touch to report problems\nand give feedback? Where can potential users find the Code of Conduct\nfor your project?\n\nThis talk is for everyone who is interested in working on open source\nprojects and wants to know how documentation can help newcomers and more\nexperienced users use your code and to encourage them to engage in the\ncommunity.\n", "copyright_text": null, - "description": "", + "description": "When starting a new project, developers, myself included, usually get\nright into hacking things, like tinkering with libraries, that we would\nlike to learn or solving a particular problem as quickly a possible.\nOccasionally we also decide to publish the resulting project to a\nsoftware repository such as PyPI for Python or NPM for Node.js etc., so\nthat others can use our nifty code, submit a pull request and maybe even\nform a community around the project.\n\nAs the creator, you might be lucky and someone will find your project on\nthe front-page of GitHub or maybe eben Hacker News or Reddit. What\nhappens next is on you really. But what does that mean?\n\nBefore jumping right to the command line and installing your package,\nthose who are interested usually try to find out what problems the\nproject is solving and how it can help them with their own. That's what\nyour README file is for - it's most likely the first thing potential\nusers read, that you control.\n\nA good README briefly and concisely explains what your software does,\nhow it can be installed and what API it exposes. You also want to\nprovide information on the requirements, the license it uses and how the\nproject is managed. Who are you? How to get in touch to report problems\nand give feedback? Where can potential users find the Code of Conduct\nfor your project?\n\nThis talk is for everyone who is interested in working on open source\nprojects and wants to know how documentation can help newcomers and more\nexperienced users use your code and to encourage them to engage in the\ncommunity.\n", "duration": 1509, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-main-takeaways-after-one-year-in-documentation-by-meike-chabowski.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-main-takeaways-after-one-year-in-documentation-by-meike-chabowski.json index b6a8cd81b..cb3bed746 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-main-takeaways-after-one-year-in-documentation-by-meike-chabowski.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-main-takeaways-after-one-year-in-documentation-by-meike-chabowski.json @@ -1,7 +1,6 @@ { - "abstract": "For 22+ years, I am working in IT \u2013 most of this time in the \u201cbusiness-\nrelated\u201d part of the game. Roughly a year ago, I decided to change\nsomething. Well \u2013 still working in IT, and still working in the same\ncompany \u2026 But I moved from a Product Marketing role (which I hold for\nabout 17 years) to R&D, because the documentation team \u201cmade me an offer\nI couldn\u2019t refuse\u201d.\n\nOf course I interacted with many of our engineers before, and of course\nI also knew most of the documentation team members before. But in\nretrospective, I can say that I somehow lived on \u201canother planet\u201d\nbefore, and that my first year as documentarian in an open source\nsoftware company was definitely deeply eye-opening for me.\n\nIf you are curious now, join the talk and hear more about my main\ntakeaways regarding documentation in general and the experiences with my\nteam in particular.\n", "copyright_text": null, - "description": "", + "description": "For 22+ years, I am working in IT \u2013 most of this time in the \u201cbusiness-\nrelated\u201d part of the game. Roughly a year ago, I decided to change\nsomething. Well \u2013 still working in IT, and still working in the same\ncompany \u2026 But I moved from a Product Marketing role (which I hold for\nabout 17 years) to R&D, because the documentation team \u201cmade me an offer\nI couldn\u2019t refuse\u201d.\n\nOf course I interacted with many of our engineers before, and of course\nI also knew most of the documentation team members before. But in\nretrospective, I can say that I somehow lived on \u201canother planet\u201d\nbefore, and that my first year as documentarian in an open source\nsoftware company was definitely deeply eye-opening for me.\n\nIf you are curious now, join the talk and hear more about my main\ntakeaways regarding documentation in general and the experiences with my\nteam in particular.\n", "duration": 1380, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-microaggressions-inclusive-language-by-cory-williamson-cardneau.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-microaggressions-inclusive-language-by-cory-williamson-cardneau.json index 6e2abed6d..dc8626f81 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-microaggressions-inclusive-language-by-cory-williamson-cardneau.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-microaggressions-inclusive-language-by-cory-williamson-cardneau.json @@ -1,7 +1,6 @@ { - "abstract": "You've heard about diversity problems in tech, right? We know the\nproblem exists at every point in the process: education, internship\nopportunities, hiring. We don't talk much about what happens to the\npeople we *do* work with.\n\nAs documentarians, we spend a lot of time thinking about the best words\nto use for our products, tutorials, manuals. We know that words matter.\n\"Microaggressions\" are the small indignities that people of color,\nnon-cis- gendered folks, women, and others experience on a daily basis.\nMicroaggressions at work tell us, over and over, that we don't really\nbelong in that workplace. So let's talk about the words we use with our\ncoworkers. Let's talk about how we can all make diversity a daily\npractice at work, not just a hiring problem.\n", "copyright_text": null, - "description": "", + "description": "You've heard about diversity problems in tech, right? We know the\nproblem exists at every point in the process: education, internship\nopportunities, hiring. We don't talk much about what happens to the\npeople we *do* work with.\n\nAs documentarians, we spend a lot of time thinking about the best words\nto use for our products, tutorials, manuals. We know that words matter.\n\"Microaggressions\" are the small indignities that people of color,\nnon-cis- gendered folks, women, and others experience on a daily basis.\nMicroaggressions at work tell us, over and over, that we don't really\nbelong in that workplace. So let's talk about the words we use with our\ncoworkers. Let's talk about how we can all make diversity a daily\npractice at work, not just a hiring problem.\n", "duration": 1474, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-requirements-that-you-didn-t-know-were-there-by-lesia-zasadna.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-requirements-that-you-didn-t-know-were-there-by-lesia-zasadna.json index b12809e42..269947160 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-requirements-that-you-didn-t-know-were-there-by-lesia-zasadna.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-requirements-that-you-didn-t-know-were-there-by-lesia-zasadna.json @@ -1,7 +1,6 @@ { - "abstract": "Any doc - every doc - that you deliver, it's only as useful as the\nrequirements it satisfies. Typical requirements revolve around target\naudience, method of delivery, technical limitations. But after the doc\nis done, then come unexpected expectations.\n\nSuddenly, your docs should not only make users happy, but also help your\nstakeholders achieve their aims - move up a career ladder, impress the\nboss, get a bigger paycheck.\n\nThe success of your docs depends on things you are never told. This talk\nis about reading your stakeholders and deducing the ultimate\nrequirements.\n", "copyright_text": null, - "description": "", + "description": "Any doc - every doc - that you deliver, it's only as useful as the\nrequirements it satisfies. Typical requirements revolve around target\naudience, method of delivery, technical limitations. But after the doc\nis done, then come unexpected expectations.\n\nSuddenly, your docs should not only make users happy, but also help your\nstakeholders achieve their aims - move up a career ladder, impress the\nboss, get a bigger paycheck.\n\nThe success of your docs depends on things you are never told. This talk\nis about reading your stakeholders and deducing the ultimate\nrequirements.\n", "duration": 1631, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-tech-writers-without-borders-by-stuart-culshaw.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-tech-writers-without-borders-by-stuart-culshaw.json index cc4e2736f..05a2fc244 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-tech-writers-without-borders-by-stuart-culshaw.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-tech-writers-without-borders-by-stuart-culshaw.json @@ -1,7 +1,6 @@ { - "abstract": "Created in 2016, Tech Writers Without Borders aims to connect technical\ncommunicators with nonprofits seeking help with their documentation and\ntraining materials.\n\nUsing examples from our work with iNERDE, a social enterprise seeking to\nempower West African youth with Science, Technology, Engineering and\nMath education, I will describe the many ways in which technical\ncommunicators can make a real difference to the operational\neffectiveness of nonprofits and the lives of those they serve.\n\nIf you, too, are interested in volunteering your skills for social\nimpact, this session will hopefully inspire you to action, or, at the\nvery least encourage you to view the value of your craft in a new light.\n", "copyright_text": null, - "description": "", + "description": "Created in 2016, Tech Writers Without Borders aims to connect technical\ncommunicators with nonprofits seeking help with their documentation and\ntraining materials.\n\nUsing examples from our work with iNERDE, a social enterprise seeking to\nempower West African youth with Science, Technology, Engineering and\nMath education, I will describe the many ways in which technical\ncommunicators can make a real difference to the operational\neffectiveness of nonprofits and the lives of those they serve.\n\nIf you, too, are interested in volunteering your skills for social\nimpact, this session will hopefully inspire you to action, or, at the\nvery least encourage you to view the value of your craft in a new light.\n", "duration": 1641, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-telling-a-great-story-on-github-by-lauri-apple.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-telling-a-great-story-on-github-by-lauri-apple.json index db6273964..6efd30568 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-telling-a-great-story-on-github-by-lauri-apple.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-telling-a-great-story-on-github-by-lauri-apple.json @@ -1,7 +1,6 @@ { - "abstract": "As a former journalist, I tend to think in terms of storytelling. As an\nopen source evangelist, I invite you to do the same. What you share on\nGitHub tells a story about you, your development practices, and your\nopenness to others in the open source community. If you're motivated to\ngain users, contributors, and positive feedback about your projects,\nthen building a compelling, coherent narrative is essential.\n\nIn this presentation, I'll share insights gained from curating Zalando's\nGitHub repository so we can tell a better story. I'll describe how we've\nused GitHub and other tools to create guidelines and processes that\nbring sanity to our storytelling. And I'll talk about how focusing on\nhigher-quality docs has helped us to instill a stronger product mindset\nin our development teams. Writing a README, for example, offers an\nopportunity to tell the world why a project exists, how it works (and\nwhy), what makes it unique, and how it might evolve over time. I'll\ndiscuss how this process not only empowers developers, but also those of\nus who are technical writers and storytellers\u2014offering several real-life\nexamples to (hopefully) inspire you.\n\nFrom 400+ projects of widely differing quality, reliability and\nmaintenance levels, we've winnowed our OSS offerings at Zalando to make\nour highest- quality work more discoverable and user-friendly. If your\norganization is facing GitHub-bloat challenges, looking for ways to\nmanage your repos more effectively, or wondering how better docs can\nhelp your OSS efforts succeed, you might find some help here.\n", "copyright_text": null, - "description": "", + "description": "As a former journalist, I tend to think in terms of storytelling. As an\nopen source evangelist, I invite you to do the same. What you share on\nGitHub tells a story about you, your development practices, and your\nopenness to others in the open source community. If you're motivated to\ngain users, contributors, and positive feedback about your projects,\nthen building a compelling, coherent narrative is essential.\n\nIn this presentation, I'll share insights gained from curating Zalando's\nGitHub repository so we can tell a better story. I'll describe how we've\nused GitHub and other tools to create guidelines and processes that\nbring sanity to our storytelling. And I'll talk about how focusing on\nhigher-quality docs has helped us to instill a stronger product mindset\nin our development teams. Writing a README, for example, offers an\nopportunity to tell the world why a project exists, how it works (and\nwhy), what makes it unique, and how it might evolve over time. I'll\ndiscuss how this process not only empowers developers, but also those of\nus who are technical writers and storytellers\u2014offering several real-life\nexamples to (hopefully) inspire you.\n\nFrom 400+ projects of widely differing quality, reliability and\nmaintenance levels, we've winnowed our OSS offerings at Zalando to make\nour highest- quality work more discoverable and user-friendly. If your\norganization is facing GitHub-bloat challenges, looking for ways to\nmanage your repos more effectively, or wondering how better docs can\nhelp your OSS efforts succeed, you might find some help here.\n", "duration": 1882, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-trustworthy-and-sensible-api-docs-with-graphql-by-garen-torikian.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-trustworthy-and-sensible-api-docs-with-graphql-by-garen-torikian.json index 64f414c83..b198442fa 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-trustworthy-and-sensible-api-docs-with-graphql-by-garen-torikian.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-trustworthy-and-sensible-api-docs-with-graphql-by-garen-torikian.json @@ -1,7 +1,6 @@ { - "abstract": "GitHub is migrating its public API system from REST to GraphQL. In this\ntalk, I'd like to go over my personal experiences writing API\ndocumentation for ten years, and why GraphQL's \"everything needs\ndocumentation\" approach is a much needed improvement. I'd go over past\nAPI tooling and methodologies, current best practices to make \"sane\"\nautogenerated API documentation, and why I think that GraphQL is a boon\nfor technical writers, developers, and end users.\n", "copyright_text": null, - "description": "", + "description": "GitHub is migrating its public API system from REST to GraphQL. In this\ntalk, I'd like to go over my personal experiences writing API\ndocumentation for ten years, and why GraphQL's \"everything needs\ndocumentation\" approach is a much needed improvement. I'd go over past\nAPI tooling and methodologies, current best practices to make \"sane\"\nautogenerated API documentation, and why I think that GraphQL is a boon\nfor technical writers, developers, and end users.\n", "duration": 1565, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-what-nobody-tells-you-about-documentation-by-daniele-procida.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-what-nobody-tells-you-about-documentation-by-daniele-procida.json index ac005a76a..4301ecfdb 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-what-nobody-tells-you-about-documentation-by-daniele-procida.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-what-nobody-tells-you-about-documentation-by-daniele-procida.json @@ -1,7 +1,6 @@ { - "abstract": "Nearly everyone agrees that good documentation is important to the\nsuccess of software projects, and yet very few projects actually have\ngood documentation. Even successful projects often have barely adequate\ndocumentation.\n\nOften, it\u2019s not for want of effort - the project\u2019s developers have\nworked hard on it - nor for lack of documentation - the authors have\nproduced a lot of it.\n\nIt simply turns out to be not very good - not helpful enough for the\nusers who should be able to rely on it, and a depressing chore for the\nauthors who have to maintain it.\n\nThe good news is that both these problems can be solved by understanding\nhow documentation works, and that there are four distinct kinds of\ndocumentation - with four distinct functions. The four kinds of\ndocumentation are:\n\n- learning-oriented tutorials\n\n- goal-oriented how-to guides\n\n- understanding-oriented discussions\n\n- information-oriented reference material\n\nStructuring documentation according to its four distinct functions helps\nensure that each of them is adequately served. It also makes it far\neasier to write and maintain.\n\nUsing real-life examples I\u2019ll draw out the key functions of\ndocumentation, and how they map onto different ways of writing it.\nPutting this into practice is simple when armed with some basic\nguidelines. The benefits are huge, and available with a minimum of\neffort.\n\nI won\u2019t be discussing documentation tools or software or other topics\nthat have been covered amply elsewhere, but some neglected and\npoorly-understood aspects of documentation that will make your software\nprojects and teams more successful.\n", "copyright_text": null, - "description": "", + "description": "Nearly everyone agrees that good documentation is important to the\nsuccess of software projects, and yet very few projects actually have\ngood documentation. Even successful projects often have barely adequate\ndocumentation.\n\nOften, it\u2019s not for want of effort - the project\u2019s developers have\nworked hard on it - nor for lack of documentation - the authors have\nproduced a lot of it.\n\nIt simply turns out to be not very good - not helpful enough for the\nusers who should be able to rely on it, and a depressing chore for the\nauthors who have to maintain it.\n\nThe good news is that both these problems can be solved by understanding\nhow documentation works, and that there are four distinct kinds of\ndocumentation - with four distinct functions. The four kinds of\ndocumentation are:\n\n- learning-oriented tutorials\n\n- goal-oriented how-to guides\n\n- understanding-oriented discussions\n\n- information-oriented reference material\n\nStructuring documentation according to its four distinct functions helps\nensure that each of them is adequately served. It also makes it far\neasier to write and maintain.\n\nUsing real-life examples I\u2019ll draw out the key functions of\ndocumentation, and how they map onto different ways of writing it.\nPutting this into practice is simple when armed with some basic\nguidelines. The benefits are huge, and available with a minimum of\neffort.\n\nI won\u2019t be discussing documentation tools or software or other topics\nthat have been covered amply elsewhere, but some neglected and\npoorly-understood aspects of documentation that will make your software\nprojects and teams more successful.\n", "duration": 1748, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-writing-a-book-in-2017-by-thomas-parisot.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-writing-a-book-in-2017-by-thomas-parisot.json index ce7fa2cf6..671bc8849 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-writing-a-book-in-2017-by-thomas-parisot.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-writing-a-book-in-2017-by-thomas-parisot.json @@ -1,7 +1,6 @@ { - "abstract": "The usual way of writing a technical book is to open the Word or\nLibreOffice application, to write some content, to make a backup, to\nsend it by email to the publisher and to deal with the feedbacks. And\nrepeat.\n\nHowever in 2017 we can do differently by using open formats like\nAsciidoc, by using version control to propagate changes, by using\ncollaborative platforms like GitHub or GitLab to collate feedbacks in\nany form as well as transforming text and code into readable and\ninteractive artefacts.\n\nIt gives us a unique opportunity to approach the whole process of\nwriting in term of \"content experience\", of \"toolchain\" and of\n\"distribution\".\n\nIn the end, a \"book\" becomes a \"writing format\" as we can reuse the same\npattern to manage any kind of \"content\" \u2014 articles, publications,\nessays, documentation \u2014 that we can transform in physical books,\ne-books, interactive web pages etc.\n", "copyright_text": null, - "description": "", + "description": "The usual way of writing a technical book is to open the Word or\nLibreOffice application, to write some content, to make a backup, to\nsend it by email to the publisher and to deal with the feedbacks. And\nrepeat.\n\nHowever in 2017 we can do differently by using open formats like\nAsciidoc, by using version control to propagate changes, by using\ncollaborative platforms like GitHub or GitLab to collate feedbacks in\nany form as well as transforming text and code into readable and\ninteractive artefacts.\n\nIt gives us a unique opportunity to approach the whole process of\nwriting in term of \"content experience\", of \"toolchain\" and of\n\"distribution\".\n\nIn the end, a \"book\" becomes a \"writing format\" as we can reuse the same\npattern to manage any kind of \"content\" \u2014 articles, publications,\nessays, documentation \u2014 that we can transform in physical books,\ne-books, interactive web pages etc.\n", "duration": 1497, "language": "eng", "recorded": "2017-09-11", diff --git a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-writing-great-getting-started-documentation-by-tim-rogers.json b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-writing-great-getting-started-documentation-by-tim-rogers.json index cde798562..8c2ae8849 100644 --- a/writethedocs-eu-2017/videos/write-the-docs-prague-2017-writing-great-getting-started-documentation-by-tim-rogers.json +++ b/writethedocs-eu-2017/videos/write-the-docs-prague-2017-writing-great-getting-started-documentation-by-tim-rogers.json @@ -1,7 +1,6 @@ { - "abstract": "As the old saying goes, \u201cyou never get a second chance to make a first\nimpression\u201d. When you first meet someone new (not least at a conference\nfor documentarians!), those first few moments set the tone. In exactly\nthe same way, the experience your user has when they first \u201cmeet\u201d your\nproduct and get to grips with it will set the tone for your entire\nrelationship with them.\n\nAs documentarians, we so often focus on building detailed and exhaustive\n\u201creference\u201d documentation, but in doing that, we forget to provide the\nright kind of \u201cgetting started\u201d experience for a user brand new to our\nproduct.\n\nAt GoCardless, we spent the first years of the life of our platform\nfocused on building high-quality reference documentation. But in Summer\n2016, we kicked off a big piece of work on a new set of resources: a\n\u201cgetting started\u201d guide for our API, getting the user from\nnought-to-sixty on our developer platform.\n\nTo make the right first impression, we had to turn things on their head\nand think from the reader\u2019s perspective. From this perspective, what\nwe\u2019ll write and build looks very different to our \u201creference\u201d\ndocumentation, seeking not only to teach the user how to use our\nproduct, but also to explain the fundamental concepts behind it and to\nbring the user to the all-important \u201caha!\u201d moment where they see the\nvalue in what we\u2019re offering.\n\nIn this talk, I\u2019ll go through:\n\n- the fundamental differences between \u201creference\u201d and \u201cgetting started\u201d\n documentation\n\n- the lessons we learnt on the way as we experimented and spent\n extensive time with end users\n\n- what we built\n\n- the results \u2014 from our users\u2019 perspective, and in terms of how we\n build demand within the company for further \u201cgetting started\u201d content\n", "copyright_text": null, - "description": "", + "description": "As the old saying goes, \u201cyou never get a second chance to make a first\nimpression\u201d. When you first meet someone new (not least at a conference\nfor documentarians!), those first few moments set the tone. In exactly\nthe same way, the experience your user has when they first \u201cmeet\u201d your\nproduct and get to grips with it will set the tone for your entire\nrelationship with them.\n\nAs documentarians, we so often focus on building detailed and exhaustive\n\u201creference\u201d documentation, but in doing that, we forget to provide the\nright kind of \u201cgetting started\u201d experience for a user brand new to our\nproduct.\n\nAt GoCardless, we spent the first years of the life of our platform\nfocused on building high-quality reference documentation. But in Summer\n2016, we kicked off a big piece of work on a new set of resources: a\n\u201cgetting started\u201d guide for our API, getting the user from\nnought-to-sixty on our developer platform.\n\nTo make the right first impression, we had to turn things on their head\nand think from the reader\u2019s perspective. From this perspective, what\nwe\u2019ll write and build looks very different to our \u201creference\u201d\ndocumentation, seeking not only to teach the user how to use our\nproduct, but also to explain the fundamental concepts behind it and to\nbring the user to the all-important \u201caha!\u201d moment where they see the\nvalue in what we\u2019re offering.\n\nIn this talk, I\u2019ll go through:\n\n- the fundamental differences between \u201creference\u201d and \u201cgetting started\u201d\n documentation\n\n- the lessons we learnt on the way as we experimented and spent\n extensive time with end users\n\n- what we built\n\n- the results \u2014 from our users\u2019 perspective, and in terms of how we\n build demand within the company for further \u201cgetting started\u201d content\n", "duration": 1693, "language": "eng", "recorded": "2017-09-11", From 2b07fd00fc496c983aa6fb9f329ad55ee0faa104 Mon Sep 17 00:00:00 2001 From: Jon Banafato Date: Mon, 29 Jul 2024 16:13:08 -0400 Subject: [PATCH 6/7] Write The Docs EU 2016: move talk abstracts into description field --- ...ills-feedback-handling-community-wrangling-panhandling.json | 3 +-- ...-beyond-software-learning-from-other-technical-writers.json | 3 +-- .../videos/daniel-beck-checklist-the-docs.json | 3 +-- ...oliver-documentoring-growing-a-love-the-docs-community.json | 3 +-- .../istvan-zoltan-szabo-writing-as-a-non-native-speaker.json | 3 +-- ...se-using-meaningful-names-to-improve-api-documentation.json | 3 +-- ...an-wendt-operations-technical-writing-for-data-centers.json | 3 +-- writethedocs-eu-2016/videos/kata-nagygyorgy-poll-the-docs.json | 3 +-- ...-eker-jennifer-rondeau-docs-as-code-the-missing-manual.json | 3 +-- ...exploring-the-information-needs-of-software-developers.json | 3 +-- .../videos/paul-adams-postulating-the-backlog-laxative.json | 3 +-- ...velocity-docs-that-keep-pace-with-rapid-release-cycles.json | 3 +-- ...na-macnamara-as-good-as-it-gets-why-better-trumps-best.json | 3 +-- ...cro-architecture-grammar-syntax-and-cognitive-rhetoric.json | 3 +-- ...ambers-documentarians-and-support-work-better-together.json | 3 +-- ...ating-an-information-experience-in-the-atlassian-voice.json | 3 +-- ...pnil-ogale-when-bad-screenshots-happen-to-good-writers.json | 3 +-- ...riting-fiction-teaches-you-about-writing-documentation.json | 3 +-- 18 files changed, 18 insertions(+), 36 deletions(-) diff --git a/writethedocs-eu-2016/videos/chris-mills-feedback-handling-community-wrangling-panhandling.json b/writethedocs-eu-2016/videos/chris-mills-feedback-handling-community-wrangling-panhandling.json index 9303bc6e4..af1c37189 100644 --- a/writethedocs-eu-2016/videos/chris-mills-feedback-handling-community-wrangling-panhandling.json +++ b/writethedocs-eu-2016/videos/chris-mills-feedback-handling-community-wrangling-panhandling.json @@ -1,7 +1,6 @@ { - "abstract": "Feedback is a big deal. As tech writers we want to receive adultation\nwhen the docs rock, or constructive criticism when there is cleanup\nrequired. Or EVEN BETTER, we want the engineers/community members/reddit\nreaders/clowns giving the feedback to come on board and help fix the\nproblems.\n\nBut. Actually tweaking the signal to noise ratio to something useful is\nreally difficult. Especially when you are curating a site as enormous as\nMDN, the content of which is open licensed, multilingual, and open for\npublic editing.\n\nIn this talk, MDN writer Chris Mills discusses topics such as how to\nchoose the right feedback mechanism(s) for your situation, how to stem\nthe torrent and get the right kind of feedback and contributions\n(actually useful), effective begging, stealing and borrowing, and how to\nbalance being firm and keeping control of your product with being\ndiplomatic and being able to sleep at night.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-chris-mills\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "Feedback is a big deal. As tech writers we want to receive adultation\nwhen the docs rock, or constructive criticism when there is cleanup\nrequired. Or EVEN BETTER, we want the engineers/community members/reddit\nreaders/clowns giving the feedback to come on board and help fix the\nproblems.\n\nBut. Actually tweaking the signal to noise ratio to something useful is\nreally difficult. Especially when you are curating a site as enormous as\nMDN, the content of which is open licensed, multilingual, and open for\npublic editing.\n\nIn this talk, MDN writer Chris Mills discusses topics such as how to\nchoose the right feedback mechanism(s) for your situation, how to stem\nthe torrent and get the right kind of feedback and contributions\n(actually useful), effective begging, stealing and borrowing, and how to\nbalance being firm and keeping control of your product with being\ndiplomatic and being able to sleep at night.\n", "duration": 1816, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/chris-ward-beyond-software-learning-from-other-technical-writers.json b/writethedocs-eu-2016/videos/chris-ward-beyond-software-learning-from-other-technical-writers.json index 697fcf706..a8615f321 100644 --- a/writethedocs-eu-2016/videos/chris-ward-beyond-software-learning-from-other-technical-writers.json +++ b/writethedocs-eu-2016/videos/chris-ward-beyond-software-learning-from-other-technical-writers.json @@ -1,7 +1,6 @@ { - "abstract": "Outside of my technical writing work for software projects I have been\ncreating a board game. A board game also requires mechanics to function\nand players to clearly understand how these mechanics work to use and\nappreciate fully.\n\nAs part of my research for writing game manuals I looked at manuals for\nfurniture, electronics, and cars to see how they explain to users how to\nsetup and use their products.\n\nIn this presentation I will look at how the technical writing skills of\ndifferent industries can learn from each other.\n\nThis will include:\n\n- Game Manuals and tutorials\n- Assembly instructions (e.g. those wonderful Ikea inserts)\n- Service Manuals for electronics\n\nAnd as part of looking at these case studies, the presentation will\ncover:\n\n- Iconography vs Text\n- The limitations of updating print manuals\n- Reducing language and cultural colloquialisms\n- Identifying what needs to be said and what doesn't\n\nAnd by the end of the presentation I hope that everyone will have learnt\na lot from each other and realize that we're all trying to achieve the\nsame thing(s).\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-chris-ward\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "Outside of my technical writing work for software projects I have been\ncreating a board game. A board game also requires mechanics to function\nand players to clearly understand how these mechanics work to use and\nappreciate fully.\n\nAs part of my research for writing game manuals I looked at manuals for\nfurniture, electronics, and cars to see how they explain to users how to\nsetup and use their products.\n\nIn this presentation I will look at how the technical writing skills of\ndifferent industries can learn from each other.\n\nThis will include:\n\n- Game Manuals and tutorials\n- Assembly instructions (e.g. those wonderful Ikea inserts)\n- Service Manuals for electronics\n\nAnd as part of looking at these case studies, the presentation will\ncover:\n\n- Iconography vs Text\n- The limitations of updating print manuals\n- Reducing language and cultural colloquialisms\n- Identifying what needs to be said and what doesn't\n\nAnd by the end of the presentation I hope that everyone will have learnt\na lot from each other and realize that we're all trying to achieve the\nsame thing(s).\n", "duration": 818, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/daniel-beck-checklist-the-docs.json b/writethedocs-eu-2016/videos/daniel-beck-checklist-the-docs.json index dc0ac51e4..a7760786a 100644 --- a/writethedocs-eu-2016/videos/daniel-beck-checklist-the-docs.json +++ b/writethedocs-eu-2016/videos/daniel-beck-checklist-the-docs.json @@ -1,7 +1,6 @@ { - "abstract": "The aviation industry has made flying long distances at high speeds one\nof the safest ways to travel. How did they do it? In part with the help\nof the humble but effective checklist! In this talk, you\u2019ll learn to\nadapt the checklist practices of high-risk environments, like flight\ndecks and operating rooms, to avoid mistakes and improve your\ndocumentation process.\n\nHave you ever missed an important step that you\u2019ve done a hundred times\nbefore, or are you worried that you might someday? Or have you ever\nrepeatedly made the same, avoidable mistake? A well-designed checklist\nmight help you avoid errors large and small and increase confidence in\nyour workflow. In this talk, you\u2019ll learn:\n\n- How to write a checklist that you\u2019ll actually want to use\n- How to choose the right time and place to follow your checklist\n- How to extend your checklists with automation or teamwork\n\nInspired by research and practices in aerospace safety (such as \u201c Human\nFactors of Flight Deck Checklists: The Normal Checklist\u201d by Degani &\nWiener), medical safety (such as \u201cThe Checklist Manifesto\u201d by Atul\nGawande), and cognitive psychology (such as \u201cHuman Error\u201d by James\nReason), this talk will guide you through the process of making and\nusing checklists in the day-to-day work of creating documentation.\n\nFrom what distinguishes a checklist from a to-do list to developing\nchecklist habits, you\u2019ll learn how to use checklists to help you write\nthe docs.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-daniel-beck\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "The aviation industry has made flying long distances at high speeds one\nof the safest ways to travel. How did they do it? In part with the help\nof the humble but effective checklist! In this talk, you\u2019ll learn to\nadapt the checklist practices of high-risk environments, like flight\ndecks and operating rooms, to avoid mistakes and improve your\ndocumentation process.\n\nHave you ever missed an important step that you\u2019ve done a hundred times\nbefore, or are you worried that you might someday? Or have you ever\nrepeatedly made the same, avoidable mistake? A well-designed checklist\nmight help you avoid errors large and small and increase confidence in\nyour workflow. In this talk, you\u2019ll learn:\n\n- How to write a checklist that you\u2019ll actually want to use\n- How to choose the right time and place to follow your checklist\n- How to extend your checklists with automation or teamwork\n\nInspired by research and practices in aerospace safety (such as \u201c Human\nFactors of Flight Deck Checklists: The Normal Checklist\u201d by Degani &\nWiener), medical safety (such as \u201cThe Checklist Manifesto\u201d by Atul\nGawande), and cognitive psychology (such as \u201cHuman Error\u201d by James\nReason), this talk will guide you through the process of making and\nusing checklists in the day-to-day work of creating documentation.\n\nFrom what distinguishes a checklist from a to-do list to developing\nchecklist habits, you\u2019ll learn how to use checklists to help you write\nthe docs.\n", "duration": 1453, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/david-oliver-documentoring-growing-a-love-the-docs-community.json b/writethedocs-eu-2016/videos/david-oliver-documentoring-growing-a-love-the-docs-community.json index d56f80a6a..89c2be500 100644 --- a/writethedocs-eu-2016/videos/david-oliver-documentoring-growing-a-love-the-docs-community.json +++ b/writethedocs-eu-2016/videos/david-oliver-documentoring-growing-a-love-the-docs-community.json @@ -1,7 +1,6 @@ { - "abstract": "As documentarians, our primary goal is delivering the content that users\nneed in order to use our products. This might sound simple, but we are\noften writing about complex systems, which will be used by people of\nvarying skill levels. Our final publications may have all the words in\nthe right order, but sometimes our biggest challenge is getting access\nto the right content in the first place.\n\nDeciding on what is the right content can often be hard, and extracting\nit from the development team can be even harder. Some of us might be\nable to read the codebase to decipher what information a user will need.\nSome of us might get to sit in planning and strategy meetings to gain a\nthorough understanding of our user and their documentation requirements.\nMost of us though will find something in the middle - we sit with\ndevelopers and engineers, build relationships, and elbow our way into\ntheir process.\n\nThis talk will look at several ways in which to mentor your engineering\nand marketing specialists so that everyone in your team can contribute\nto the documentation process. I call this \"Documentoring\" - its about\ntraining the people around you to understand the requirements of a\ndocumentarian, and to truly value the docs as part of the product\nlifecycle.\n\nThrough my experience at IBM, and then at a small startup in Bristol,\nI've seen (and tried) various techniques at getting everyone in your\nteam invested in quality documentation. I'll share stories of my\nsuccesses and failures, and show you how documentation really can be a\nteam effort, even if you stand alone in your company as the sole owner\nof the docs.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-david-oliver\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "As documentarians, our primary goal is delivering the content that users\nneed in order to use our products. This might sound simple, but we are\noften writing about complex systems, which will be used by people of\nvarying skill levels. Our final publications may have all the words in\nthe right order, but sometimes our biggest challenge is getting access\nto the right content in the first place.\n\nDeciding on what is the right content can often be hard, and extracting\nit from the development team can be even harder. Some of us might be\nable to read the codebase to decipher what information a user will need.\nSome of us might get to sit in planning and strategy meetings to gain a\nthorough understanding of our user and their documentation requirements.\nMost of us though will find something in the middle - we sit with\ndevelopers and engineers, build relationships, and elbow our way into\ntheir process.\n\nThis talk will look at several ways in which to mentor your engineering\nand marketing specialists so that everyone in your team can contribute\nto the documentation process. I call this \"Documentoring\" - its about\ntraining the people around you to understand the requirements of a\ndocumentarian, and to truly value the docs as part of the product\nlifecycle.\n\nThrough my experience at IBM, and then at a small startup in Bristol,\nI've seen (and tried) various techniques at getting everyone in your\nteam invested in quality documentation. I'll share stories of my\nsuccesses and failures, and show you how documentation really can be a\nteam effort, even if you stand alone in your company as the sole owner\nof the docs.\n", "duration": 1354, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/istvan-zoltan-szabo-writing-as-a-non-native-speaker.json b/writethedocs-eu-2016/videos/istvan-zoltan-szabo-writing-as-a-non-native-speaker.json index e890e7547..3ac3cdf7a 100644 --- a/writethedocs-eu-2016/videos/istvan-zoltan-szabo-writing-as-a-non-native-speaker.json +++ b/writethedocs-eu-2016/videos/istvan-zoltan-szabo-writing-as-a-non-native-speaker.json @@ -1,7 +1,6 @@ { - "abstract": "Writing professionally in English as a non-native speaker is a\nterrifying task sometimes. \"The limits of my language mean the limits of\nmy world.\" You have less limit when writing in your mother tongue. And\nyou may experience hard boundaries when you have to deal with other\nlanguages on a professional level.\n\nAs a beginner (non-native English) content creator, I had hard times\nduring my work. Most of the problems came from me because the lack of\nconfidence and the lack of practice. To grow faster, I had to build a\nprocess (rather a routine) that I can follow during my work on a daily\nbasis. I had to find the most effective supporting tools. And maybe the\nmost important: I had to figure out how can I keep myself motivated in\nspite of every failure.\n\nHow can a junior writer overcome the initial difficulties? My\npresentation tries to answer this question through real life examples to\nhelp other juniors in their struggles. And offers some writing tools,\nhabits, and methods that may be worth to take a chance.\n\nI would like to present what I've learned during my journey so far.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-istvan-zoltan-szabo\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "Writing professionally in English as a non-native speaker is a\nterrifying task sometimes. \"The limits of my language mean the limits of\nmy world.\" You have less limit when writing in your mother tongue. And\nyou may experience hard boundaries when you have to deal with other\nlanguages on a professional level.\n\nAs a beginner (non-native English) content creator, I had hard times\nduring my work. Most of the problems came from me because the lack of\nconfidence and the lack of practice. To grow faster, I had to build a\nprocess (rather a routine) that I can follow during my work on a daily\nbasis. I had to find the most effective supporting tools. And maybe the\nmost important: I had to figure out how can I keep myself motivated in\nspite of every failure.\n\nHow can a junior writer overcome the initial difficulties? My\npresentation tries to answer this question through real life examples to\nhelp other juniors in their struggles. And offers some writing tools,\nhabits, and methods that may be worth to take a chance.\n\nI would like to present what I've learned during my journey so far.\n", "duration": 1506, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/jan-christian-krause-using-meaningful-names-to-improve-api-documentation.json b/writethedocs-eu-2016/videos/jan-christian-krause-using-meaningful-names-to-improve-api-documentation.json index 735be6065..7c296090e 100644 --- a/writethedocs-eu-2016/videos/jan-christian-krause-using-meaningful-names-to-improve-api-documentation.json +++ b/writethedocs-eu-2016/videos/jan-christian-krause-using-meaningful-names-to-improve-api-documentation.json @@ -1,7 +1,6 @@ { - "abstract": "Interaction between incorporated software-systems is often realized via\napplication programming interfaces (APIs). The API-documentation\nexplains how to use the API. If it misses important information, serious\nmisunderstandings between the API\u2019s consumer and provider can be the\nconsequence.\n\nI my talk I will show how meaningful names in the source-code can help\nfinding gaps in the API-documentation. My findings base on my\nproject-experiences and a cross-sectional study of a corpus of more than\n186.000 web service- operations. I would like to share the 20\ndescription-patterns for API- documentation I found so far. They provide\ndetailed recommendations description of specific operations. The talk\ncloses with a comparison of classical \u201eswagger-like\u201c API-documentation\nwith the presented approach.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-jan-christian-krause\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "Interaction between incorporated software-systems is often realized via\napplication programming interfaces (APIs). The API-documentation\nexplains how to use the API. If it misses important information, serious\nmisunderstandings between the API\u2019s consumer and provider can be the\nconsequence.\n\nI my talk I will show how meaningful names in the source-code can help\nfinding gaps in the API-documentation. My findings base on my\nproject-experiences and a cross-sectional study of a corpus of more than\n186.000 web service- operations. I would like to share the 20\ndescription-patterns for API- documentation I found so far. They provide\ndetailed recommendations description of specific operations. The talk\ncloses with a comparison of classical \u201eswagger-like\u201c API-documentation\nwith the presented approach.\n", "duration": 846, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/joan-wendt-operations-technical-writing-for-data-centers.json b/writethedocs-eu-2016/videos/joan-wendt-operations-technical-writing-for-data-centers.json index 345a8993e..4197c9a01 100644 --- a/writethedocs-eu-2016/videos/joan-wendt-operations-technical-writing-for-data-centers.json +++ b/writethedocs-eu-2016/videos/joan-wendt-operations-technical-writing-for-data-centers.json @@ -1,7 +1,6 @@ { - "abstract": "Operations tech writing encompasses both hardware and software, and the\nchallenge is coming up to speed on the intersecting parts of these 2\ndisciplines. More than any other type of tech writing, operations TW is\nthe art of supporting highly technical, cross-functional teams. Most\ncompanies create super secret, bleeding edge technologies to make their\ndata centers efficient, powerful, reliable, economical, and, hopefully,\ngreen. There are few opportunities to gain background info to bring\nyourself up to speed and feel confident about your technical prowess.\n\nThis is a little talked about area of TW that's growing in importance\nand demand. At Google, it's been difficult to find writers qualified to\nhandle the cross-functional complexities/hit the ground running, and the\nramp up is steep. I'll address the demands of working in this\nchallenging but fascinating field, as well as some cultural perks such\nas working with physical engineers (mechanical, electrical,\nmanufacturing), travel, and developing one's photography skills -- and\nsaying goodbye to capturing screenshots.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-joan-wendt\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "Operations tech writing encompasses both hardware and software, and the\nchallenge is coming up to speed on the intersecting parts of these 2\ndisciplines. More than any other type of tech writing, operations TW is\nthe art of supporting highly technical, cross-functional teams. Most\ncompanies create super secret, bleeding edge technologies to make their\ndata centers efficient, powerful, reliable, economical, and, hopefully,\ngreen. There are few opportunities to gain background info to bring\nyourself up to speed and feel confident about your technical prowess.\n\nThis is a little talked about area of TW that's growing in importance\nand demand. At Google, it's been difficult to find writers qualified to\nhandle the cross-functional complexities/hit the ground running, and the\nramp up is steep. I'll address the demands of working in this\nchallenging but fascinating field, as well as some cultural perks such\nas working with physical engineers (mechanical, electrical,\nmanufacturing), travel, and developing one's photography skills -- and\nsaying goodbye to capturing screenshots.\n", "duration": 1798, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/kata-nagygyorgy-poll-the-docs.json b/writethedocs-eu-2016/videos/kata-nagygyorgy-poll-the-docs.json index 33c7b5758..c5e13fa3d 100644 --- a/writethedocs-eu-2016/videos/kata-nagygyorgy-poll-the-docs.json +++ b/writethedocs-eu-2016/videos/kata-nagygyorgy-poll-the-docs.json @@ -1,7 +1,6 @@ { - "abstract": "The Write the Docs community has been growing over the past few years,\nand we're incredibly happy to see the wide diversity that it contains.\nIn the beginning of 2016 we put together a survey to investigate how\npeople are doing their jobs, what the current status is of\ndocumentation, and what the future will bring. We're calling this effort\n\"Poll the Docs\".\n\nThanks to the 100+ participants who already filled it out and shared\ntheir experiences and thoughts about documentation. We will be able to\nshare insights about the demographic background of the community, how\ndocumentarians usually start working in this field and give an overview\nof the most supported practises, tools, languages and skills.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-kata-nagygyorgy\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "The Write the Docs community has been growing over the past few years,\nand we're incredibly happy to see the wide diversity that it contains.\nIn the beginning of 2016 we put together a survey to investigate how\npeople are doing their jobs, what the current status is of\ndocumentation, and what the future will bring. We're calling this effort\n\"Poll the Docs\".\n\nThanks to the 100+ participants who already filled it out and shared\ntheir experiences and thoughts about documentation. We will be able to\nshare insights about the demographic background of the community, how\ndocumentarians usually start working in this field and give an overview\nof the most supported practises, tools, languages and skills.\n", "duration": 898, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/margaret-eker-jennifer-rondeau-docs-as-code-the-missing-manual.json b/writethedocs-eu-2016/videos/margaret-eker-jennifer-rondeau-docs-as-code-the-missing-manual.json index a123d7dd3..bb170f371 100644 --- a/writethedocs-eu-2016/videos/margaret-eker-jennifer-rondeau-docs-as-code-the-missing-manual.json +++ b/writethedocs-eu-2016/videos/margaret-eker-jennifer-rondeau-docs-as-code-the-missing-manual.json @@ -1,7 +1,6 @@ { - "abstract": "Treating docs as code, an approach that more and more teams and\ncompanies are moving toward, involves more than putting the two together\nin a repo. We discuss some of the details that often get lost in as dev\nand docs learn to work together in new ways. Because if all we do is put\ndoc files next to code files in source control, or use parts of the same\nworkflow for code and docs, we're still isolating docs as a separate\nsort of responsibility, free from the obligations of systematic review\nand testing without which code would never be accepted into production.\n\nSome missing parts of this newer approach to documentation workflow that\nwe'll discuss include:\n\n- Outlining a documentation lifecycle that describes how material moves\n from initial draft to final production, to help people unfamiliar\n with documentation development understand better how to efficiently\n manage documentation review and testing.\n- Mapping GitHub workflow clearly to documentation workflow. This can\n help writers and editors understand better just how to use GitHub\n effectively, and equally important how it can help other contributors\n (notably programmers) understand the parts of the writer workflow\n that can be lost when docs move next to code.\n- Creating an information architecture. Words need structure to provide\n meaning, usability, and discoverability. A strong content\n architecture provides logical places for adding new content,\n especially for doc projects at scale.\n- Developing and enforcing a style guide: terminology, voice, tone.\n These things make the difference between words that users might\n understand, and documentation that can truly assist.\n- Reviewing and line/copy editing. Because you wouldn't do any less for\n code, right?\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-margaret-eker\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "Treating docs as code, an approach that more and more teams and\ncompanies are moving toward, involves more than putting the two together\nin a repo. We discuss some of the details that often get lost in as dev\nand docs learn to work together in new ways. Because if all we do is put\ndoc files next to code files in source control, or use parts of the same\nworkflow for code and docs, we're still isolating docs as a separate\nsort of responsibility, free from the obligations of systematic review\nand testing without which code would never be accepted into production.\n\nSome missing parts of this newer approach to documentation workflow that\nwe'll discuss include:\n\n- Outlining a documentation lifecycle that describes how material moves\n from initial draft to final production, to help people unfamiliar\n with documentation development understand better how to efficiently\n manage documentation review and testing.\n- Mapping GitHub workflow clearly to documentation workflow. This can\n help writers and editors understand better just how to use GitHub\n effectively, and equally important how it can help other contributors\n (notably programmers) understand the parts of the writer workflow\n that can be lost when docs move next to code.\n- Creating an information architecture. Words need structure to provide\n meaning, usability, and discoverability. A strong content\n architecture provides logical places for adding new content,\n especially for doc projects at scale.\n- Developing and enforcing a style guide: terminology, voice, tone.\n These things make the difference between words that users might\n understand, and documentation that can truly assist.\n- Reviewing and line/copy editing. Because you wouldn't do any less for\n code, right?\n", "duration": 1654, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/michael-meng-api-documentation-exploring-the-information-needs-of-software-developers.json b/writethedocs-eu-2016/videos/michael-meng-api-documentation-exploring-the-information-needs-of-software-developers.json index 81aac8a21..c3f3357a0 100644 --- a/writethedocs-eu-2016/videos/michael-meng-api-documentation-exploring-the-information-needs-of-software-developers.json +++ b/writethedocs-eu-2016/videos/michael-meng-api-documentation-exploring-the-information-needs-of-software-developers.json @@ -1,7 +1,6 @@ { - "abstract": "The success of an API crucially depends on how well its documentation\nmeets the information needs of software developers. But what information\ndo developers need? What information do they want, and what information\nare they actually using when starting to learn a new API and solve\nprogramming tasks with it? In this talk, I will present the results of\nsome empirical studies I conducted with my team to better understand the\ninformation needs of software developers. One the one hand, we ran more\nthan 20 semi-structured interviews with junior and senior developers and\nasked them \u2013 among other things \u2013 to tell us about the questions they\nraise first when approaching a new API, the type of documentation they\nlook for, and general expectations and experiences regarding API\ndocumentation. Key findings derived from the interviews were then\nfollowed up on by a standardized survey in which more than 110\ndevelopers participated. Our second study took a different approach.\nInstead of asking developers what they find important about API\ndocumentation, we asked them to solve a few tasks on a simple (REST)-API\nthat was unfamiliar to them. The goal of this study was to observe how\nthe developers approach the tasks and which pieces of the documentation\nprovided with the test API they actually use. Besides presenting the\ndesign and main findings of our studies, I will also discuss\nimplications the results may have regarding the contents, structure and\ndesign of API documentation.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-michael-meng\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "The success of an API crucially depends on how well its documentation\nmeets the information needs of software developers. But what information\ndo developers need? What information do they want, and what information\nare they actually using when starting to learn a new API and solve\nprogramming tasks with it? In this talk, I will present the results of\nsome empirical studies I conducted with my team to better understand the\ninformation needs of software developers. One the one hand, we ran more\nthan 20 semi-structured interviews with junior and senior developers and\nasked them \u2013 among other things \u2013 to tell us about the questions they\nraise first when approaching a new API, the type of documentation they\nlook for, and general expectations and experiences regarding API\ndocumentation. Key findings derived from the interviews were then\nfollowed up on by a standardized survey in which more than 110\ndevelopers participated. Our second study took a different approach.\nInstead of asking developers what they find important about API\ndocumentation, we asked them to solve a few tasks on a simple (REST)-API\nthat was unfamiliar to them. The goal of this study was to observe how\nthe developers approach the tasks and which pieces of the documentation\nprovided with the test API they actually use. Besides presenting the\ndesign and main findings of our studies, I will also discuss\nimplications the results may have regarding the contents, structure and\ndesign of API documentation.\n", "duration": 1754, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/paul-adams-postulating-the-backlog-laxative.json b/writethedocs-eu-2016/videos/paul-adams-postulating-the-backlog-laxative.json index e1b15967d..b9300e2a9 100644 --- a/writethedocs-eu-2016/videos/paul-adams-postulating-the-backlog-laxative.json +++ b/writethedocs-eu-2016/videos/paul-adams-postulating-the-backlog-laxative.json @@ -1,7 +1,6 @@ { - "abstract": "So you had an idea for an awesome software product and started to build\nup your team of engineers around it. Two things are almost inevitable:\nyou chose some super cool programming language like Clojure and you're\ndoing Scrum for the process. Good for you.\n\nWhen your company grows, you end up with multiple Scrum teams. But you\nalso end up with new activities: documentation, blogging, demos,\nsubmissions to conferences to show-off your awesome heap of Clojure. How\nare you going to get all of /that/ done?\n\n\"The book\" tells you to mix all these activities in with your Scrum\nengineering teams. \"The Book\" was also probably written by someone who\nhas never had to do devrel in their lives (or, who hates devrel\nengineers). Numerous problems exist at the interface between product\nengineering and devrel and the result is your devrel backlog can get\nbacked-up.\n\nDr. Paul (not a real doctor) has the laxative you need! In this talk he\npresents his experience of structuring multiple Scrum teams at Crate.IO\nin order to loosen-up the devrel backlog: ensuring highly quality\nfeature documentation, getting out those blog posts and showing-off our\nlovely heap of Clojure\\*.\n\n\\*Crate is written in Java.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-paul-adams\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "So you had an idea for an awesome software product and started to build\nup your team of engineers around it. Two things are almost inevitable:\nyou chose some super cool programming language like Clojure and you're\ndoing Scrum for the process. Good for you.\n\nWhen your company grows, you end up with multiple Scrum teams. But you\nalso end up with new activities: documentation, blogging, demos,\nsubmissions to conferences to show-off your awesome heap of Clojure. How\nare you going to get all of /that/ done?\n\n\"The book\" tells you to mix all these activities in with your Scrum\nengineering teams. \"The Book\" was also probably written by someone who\nhas never had to do devrel in their lives (or, who hates devrel\nengineers). Numerous problems exist at the interface between product\nengineering and devrel and the result is your devrel backlog can get\nbacked-up.\n\nDr. Paul (not a real doctor) has the laxative you need! In this talk he\npresents his experience of structuring multiple Scrum teams at Crate.IO\nin order to loosen-up the devrel backlog: ensuring highly quality\nfeature documentation, getting out those blog posts and showing-off our\nlovely heap of Clojure\\*.\n\n\\*Crate is written in Java.\n", "duration": 1647, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/rachel-whitton-delivering-high-velocity-docs-that-keep-pace-with-rapid-release-cycles.json b/writethedocs-eu-2016/videos/rachel-whitton-delivering-high-velocity-docs-that-keep-pace-with-rapid-release-cycles.json index a886f41aa..c905f4c47 100644 --- a/writethedocs-eu-2016/videos/rachel-whitton-delivering-high-velocity-docs-that-keep-pace-with-rapid-release-cycles.json +++ b/writethedocs-eu-2016/videos/rachel-whitton-delivering-high-velocity-docs-that-keep-pace-with-rapid-release-cycles.json @@ -1,7 +1,6 @@ { - "abstract": "To prevent stale content and achieve a high standard of alignment with\nproducts, documentation must be a required component of the release\ncycle. At Pantheon, this means delivering each component with similar\nprecision and trust. Documentation workflows must evolve to stay instep\nwith agile and automated product pipelines.\n\nIn addition to sharing lessons learned, this talk will explore\nPantheon\u2019s strategy for delivering high-velocity docs:\n\n- Increase project visibility\n- Simplify peer reviews\n- Make bots do the scutwork\n- Write more docs\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-rachel-whitton\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "To prevent stale content and achieve a high standard of alignment with\nproducts, documentation must be a required component of the release\ncycle. At Pantheon, this means delivering each component with similar\nprecision and trust. Documentation workflows must evolve to stay instep\nwith agile and automated product pipelines.\n\nIn addition to sharing lessons learned, this talk will explore\nPantheon\u2019s strategy for delivering high-velocity docs:\n\n- Increase project visibility\n- Simplify peer reviews\n- Make bots do the scutwork\n- Write more docs\n", "duration": 1532, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/riona-macnamara-as-good-as-it-gets-why-better-trumps-best.json b/writethedocs-eu-2016/videos/riona-macnamara-as-good-as-it-gets-why-better-trumps-best.json index c26ac2383..7c8c5f95b 100644 --- a/writethedocs-eu-2016/videos/riona-macnamara-as-good-as-it-gets-why-better-trumps-best.json +++ b/writethedocs-eu-2016/videos/riona-macnamara-as-good-as-it-gets-why-better-trumps-best.json @@ -1,7 +1,6 @@ { - "abstract": "What are the characteristics of a great documentation set? Completeness?\nAccuracy? Style? Format? No! A great documentation set is one that meets\nits objectives, and sometimes the barrier to greatness is not\ndedication, skill, or passion, but a reluctance to let things go. Every\ndocument we publish should reach a certain quality threshold - but that\nthreshold varies depending on its audience, the maturity of the project,\nand the overall project goals. What matters is not that docs are\nperfect, but that they are *good enough*.\n\nBut how to determine if a doc is \"good enough\"? This talk will cover how\nto:\n\n- Define document quality\n- Establish an appropriate quality bar for a document or doc set\n- Determine if a document meets that bar.\n\nWe're all overloaded. We're all stretched for time. Every hour we spend\nmaking a doc better than it needs to be is an hour stolen from other\nprojects where we could have more impact. Choosing \"good enough\" doesn't\nmean we're lowering our standards; it means we're choosing *appropriate*\nstandards and prioritizing correctly. Don't let the perfect be the enemy\nof the good.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-riona-macnamara\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "What are the characteristics of a great documentation set? Completeness?\nAccuracy? Style? Format? No! A great documentation set is one that meets\nits objectives, and sometimes the barrier to greatness is not\ndedication, skill, or passion, but a reluctance to let things go. Every\ndocument we publish should reach a certain quality threshold - but that\nthreshold varies depending on its audience, the maturity of the project,\nand the overall project goals. What matters is not that docs are\nperfect, but that they are *good enough*.\n\nBut how to determine if a doc is \"good enough\"? This talk will cover how\nto:\n\n- Define document quality\n- Establish an appropriate quality bar for a document or doc set\n- Determine if a document meets that bar.\n\nWe're all overloaded. We're all stretched for time. Every hour we spend\nmaking a doc better than it needs to be is an hour stolen from other\nprojects where we could have more impact. Choosing \"good enough\" doesn't\nmean we're lowering our standards; it means we're choosing *appropriate*\nstandards and prioritizing correctly. Don't let the perfect be the enemy\nof the good.\n", "duration": 1243, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/rory-tanner-information-micro-architecture-grammar-syntax-and-cognitive-rhetoric.json b/writethedocs-eu-2016/videos/rory-tanner-information-micro-architecture-grammar-syntax-and-cognitive-rhetoric.json index 6df40be32..d232dc3f6 100644 --- a/writethedocs-eu-2016/videos/rory-tanner-information-micro-architecture-grammar-syntax-and-cognitive-rhetoric.json +++ b/writethedocs-eu-2016/videos/rory-tanner-information-micro-architecture-grammar-syntax-and-cognitive-rhetoric.json @@ -1,7 +1,6 @@ { - "abstract": "Most discussions of information architecture (IA) treat it as a\nhigh-level discipline: it\u2019s that thing we do site-wide, obsessing\nhappily about taxonomies, hierarchies, and metadata, so that our content\nis more maintainable, navigable, and searchable. But what do your\nreaders do when they actually find the information that they\u2019re looking\nfor? They read it. They read the words. Where\u2019 s your information\narchitecture now?\n\nIn this talk I\u2019ll identify a few different ways that we can apply IA\nprinciples productively also at the micro levels of paragraph, sentence,\nand phrase. We\u2019ll focus on a series of syntactic structures that prove\ntheir special architectural significance, based on the results of\nongoing content testing at docs.shopify.com and on recent work in the\nfield of psycholinguistics. These key examples show how far we can\nimprove sentence processing speed, and thereby reader engagement, when\nwe use grammar deliberately as information micro-architecture. The\ncomposition and revision strategies that this approach suggests are\nespecially useful for anyone who\u2019s writing, editing, or optimizing\ncontent for use at scale.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-rory-tanner\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "Most discussions of information architecture (IA) treat it as a\nhigh-level discipline: it\u2019s that thing we do site-wide, obsessing\nhappily about taxonomies, hierarchies, and metadata, so that our content\nis more maintainable, navigable, and searchable. But what do your\nreaders do when they actually find the information that they\u2019re looking\nfor? They read it. They read the words. Where\u2019 s your information\narchitecture now?\n\nIn this talk I\u2019ll identify a few different ways that we can apply IA\nprinciples productively also at the micro levels of paragraph, sentence,\nand phrase. We\u2019ll focus on a series of syntactic structures that prove\ntheir special architectural significance, based on the results of\nongoing content testing at docs.shopify.com and on recent work in the\nfield of psycholinguistics. These key examples show how far we can\nimprove sentence processing speed, and thereby reader engagement, when\nwe use grammar deliberately as information micro-architecture. The\ncomposition and revision strategies that this approach suggests are\nespecially useful for anyone who\u2019s writing, editing, or optimizing\ncontent for use at scale.\n", "duration": 878, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/sarah-chambers-documentarians-and-support-work-better-together.json b/writethedocs-eu-2016/videos/sarah-chambers-documentarians-and-support-work-better-together.json index a4352858f..24a68e9ff 100644 --- a/writethedocs-eu-2016/videos/sarah-chambers-documentarians-and-support-work-better-together.json +++ b/writethedocs-eu-2016/videos/sarah-chambers-documentarians-and-support-work-better-together.json @@ -1,7 +1,6 @@ { - "abstract": "Do you know what the support agents are doing over in their corner? It\u2019s\nnot all cat gifs and angry users. There\u2019s real value to be found in\nworking together with your support team. They are a direct line to your\nusers!\n\nIt can definitely be difficult to bridge this gap between disciplines,\nbut your goals are 100% the same: help the customer do The Thing.\nBecause support literally spends all day talking to customers, they have\na ton of amazing data about the effectiveness of documentation, and the\ntasks customers are trying to accomplish.\n\nBuilding a better relationship with your support team will help you\nbuild a better relationship with your users. I\u2019ve seen first hand how\ncoordination drives a well executed user experience all the way from\nself service to hands- on support. Work together better and see tangible\nresults in your user happiness!\n\nIn this talk, I\u2019ll show you: \u00b7 the value of having support and technical\nwriting aligned \u00b7 how to break down the silos between teams and work\neffectively together \u00b7 how to access and use the glorious data that\nsupport is already collecting \u00b7 the metrics that matter for support-led\nuser assistance\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-sarah-chambers\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "Do you know what the support agents are doing over in their corner? It\u2019s\nnot all cat gifs and angry users. There\u2019s real value to be found in\nworking together with your support team. They are a direct line to your\nusers!\n\nIt can definitely be difficult to bridge this gap between disciplines,\nbut your goals are 100% the same: help the customer do The Thing.\nBecause support literally spends all day talking to customers, they have\na ton of amazing data about the effectiveness of documentation, and the\ntasks customers are trying to accomplish.\n\nBuilding a better relationship with your support team will help you\nbuild a better relationship with your users. I\u2019ve seen first hand how\ncoordination drives a well executed user experience all the way from\nself service to hands- on support. Work together better and see tangible\nresults in your user happiness!\n\nIn this talk, I\u2019ll show you: \u00b7 the value of having support and technical\nwriting aligned \u00b7 how to break down the silos between teams and work\neffectively together \u00b7 how to access and use the glorious data that\nsupport is already collecting \u00b7 the metrics that matter for support-led\nuser assistance\n", "duration": 1418, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/sarah-karp-watch-that-tone-creating-an-information-experience-in-the-atlassian-voice.json b/writethedocs-eu-2016/videos/sarah-karp-watch-that-tone-creating-an-information-experience-in-the-atlassian-voice.json index 5bdd4d11a..e07d3b2ec 100644 --- a/writethedocs-eu-2016/videos/sarah-karp-watch-that-tone-creating-an-information-experience-in-the-atlassian-voice.json +++ b/writethedocs-eu-2016/videos/sarah-karp-watch-that-tone-creating-an-information-experience-in-the-atlassian-voice.json @@ -1,7 +1,6 @@ { - "abstract": "Two years ago, Atlassian had no consistent voice guidelines across its\ncontent channels and product suite, creating a disjointed brand\nexperience. Today, our Information Experience writers now own the\nAtlassian voice and tone, and are teaching everyone from developers,\nproduct managers, designers, and marketers how to voicify their content.\n\nIn this talk, Sarah Karp (Information Experience Team Lead) will answer\nthe following questions:\n\n- What is the Atlassian voice?\n- Why is a consistent voice important?\n- How can you apply voice and tone to a piece of UI copy?\n\nAlong the way, Sarah will share ways in which the Information Experience\nwriters have applied voicify guidelines across the entire organization.\nShe'll also share a couple of lessons on voice and tone gone wrong and\nhow to learn from those mistakes.\n\nAt the end of the talk, you'll come away with an understanding of why\nsuccessful products have a distinctive voice and tone. You'll also come\naway with great examples of voice and tone wins (and fails), and\npractical tips about how to create voicify guidelines for writers and\nnon-writers alike.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-sarah-karp\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "Two years ago, Atlassian had no consistent voice guidelines across its\ncontent channels and product suite, creating a disjointed brand\nexperience. Today, our Information Experience writers now own the\nAtlassian voice and tone, and are teaching everyone from developers,\nproduct managers, designers, and marketers how to voicify their content.\n\nIn this talk, Sarah Karp (Information Experience Team Lead) will answer\nthe following questions:\n\n- What is the Atlassian voice?\n- Why is a consistent voice important?\n- How can you apply voice and tone to a piece of UI copy?\n\nAlong the way, Sarah will share ways in which the Information Experience\nwriters have applied voicify guidelines across the entire organization.\nShe'll also share a couple of lessons on voice and tone gone wrong and\nhow to learn from those mistakes.\n\nAt the end of the talk, you'll come away with an understanding of why\nsuccessful products have a distinctive voice and tone. You'll also come\naway with great examples of voice and tone wins (and fails), and\npractical tips about how to create voicify guidelines for writers and\nnon-writers alike.\n", "duration": 1254, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/swapnil-ogale-when-bad-screenshots-happen-to-good-writers.json b/writethedocs-eu-2016/videos/swapnil-ogale-when-bad-screenshots-happen-to-good-writers.json index c1c5fb222..51ae12458 100644 --- a/writethedocs-eu-2016/videos/swapnil-ogale-when-bad-screenshots-happen-to-good-writers.json +++ b/writethedocs-eu-2016/videos/swapnil-ogale-when-bad-screenshots-happen-to-good-writers.json @@ -1,7 +1,6 @@ { - "abstract": "You have your content moving at a swift pace, your documents are getting\nreviewed in a timely fashion (surprise!) and you are nicely heading\ntowards your release milestone. The only thing missing are some key\nscreenshots that you need to put in before you publish your\ndocumentation. What you get instead are some hideous images posing as\nscreenshots, that were captured randomly, bears no resemblance to your\ninstructions and would make no sense whatsoever to the end user.\n\nWe (documentarians) know how this usually pans out.\n\nThis talk is about when bad screenshots happen to good writers.\n\nIn my presentation, I will talk about:\n\n1. Why do we need screenshots and who provides these screenshots?\n2. What is the outcome of bad screenshots?\n3. Can we do something about acquiring screenshots in a standard manner?\n4. What are some best practices everyone can use for screenshots?\n5. Some examples of really useless screenshots.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-swapnil-ogale\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "You have your content moving at a swift pace, your documents are getting\nreviewed in a timely fashion (surprise!) and you are nicely heading\ntowards your release milestone. The only thing missing are some key\nscreenshots that you need to put in before you publish your\ndocumentation. What you get instead are some hideous images posing as\nscreenshots, that were captured randomly, bears no resemblance to your\ninstructions and would make no sense whatsoever to the end user.\n\nWe (documentarians) know how this usually pans out.\n\nThis talk is about when bad screenshots happen to good writers.\n\nIn my presentation, I will talk about:\n\n1. Why do we need screenshots and who provides these screenshots?\n2. What is the outcome of bad screenshots?\n3. Can we do something about acquiring screenshots in a standard manner?\n4. What are some best practices everyone can use for screenshots?\n5. Some examples of really useless screenshots.\n", "duration": 795, "language": "eng", "recorded": "2016-09-18", diff --git a/writethedocs-eu-2016/videos/thursday-bram-what-writing-fiction-teaches-you-about-writing-documentation.json b/writethedocs-eu-2016/videos/thursday-bram-what-writing-fiction-teaches-you-about-writing-documentation.json index fa8907b58..cc8d0f201 100644 --- a/writethedocs-eu-2016/videos/thursday-bram-what-writing-fiction-teaches-you-about-writing-documentation.json +++ b/writethedocs-eu-2016/videos/thursday-bram-what-writing-fiction-teaches-you-about-writing-documentation.json @@ -1,7 +1,6 @@ { - "abstract": "Writing fiction and writing documentation have much more in common that\ntyping out large blocks of text. This talk will talk about elements of\nfiction writing that improve the process of writing docs: Understanding\naudience: the tools fiction writers use to understand their audience (as\nwell as to communicate with them) offer deeper looks at who reads what.\nThe process of connecting with an audience is integral to fiction, but\noften overlooked in documentation \u2014 resulting in hard-to-use docs that\ndon\u2019t help users. Building story arcs: arguably, all fiction boils down\nto about seven different plots, retold in millions of different ways.\nUnderstanding underlying story structure makes the process of writing\nnew tales much easier. Those story structures and plot elements can map\ndirectly to parts of documentation, as well as show options for creating\nstanding elements for documentation. \\* Writing prose worth reading:\ndocumentation can be enjoyable to read, provided a writer is willing to\ninvest time in crafting good reading material. This talk will draw on\nexamples from both popular fiction and documentation out in the world\ntoday.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2016/speakers/#speaker-eu-2016-thursday-bram\n\nFollow us on Twitter @writethedocs\nJoin our next events: http://www.writethedocs.org/", + "description": "Writing fiction and writing documentation have much more in common that\ntyping out large blocks of text. This talk will talk about elements of\nfiction writing that improve the process of writing docs: Understanding\naudience: the tools fiction writers use to understand their audience (as\nwell as to communicate with them) offer deeper looks at who reads what.\nThe process of connecting with an audience is integral to fiction, but\noften overlooked in documentation \u2014 resulting in hard-to-use docs that\ndon\u2019t help users. Building story arcs: arguably, all fiction boils down\nto about seven different plots, retold in millions of different ways.\nUnderstanding underlying story structure makes the process of writing\nnew tales much easier. Those story structures and plot elements can map\ndirectly to parts of documentation, as well as show options for creating\nstanding elements for documentation. \\* Writing prose worth reading:\ndocumentation can be enjoyable to read, provided a writer is willing to\ninvest time in crafting good reading material. This talk will draw on\nexamples from both popular fiction and documentation out in the world\ntoday.\n", "duration": 1828, "language": "eng", "recorded": "2016-09-18", From 111776bc8851325cc2225d78b7f11053d86ffd7e Mon Sep 17 00:00:00 2001 From: Jon Banafato Date: Mon, 29 Jul 2024 16:14:57 -0400 Subject: [PATCH 7/7] Write The Docs EU 2015: move talk abstracts into description field --- ...rect-how-to-make-sure-your-documentation-keeps-working.json | 3 +-- ...quest-for-scientific-credit-for-software-documentation.json | 3 +-- ...eth-aitman-before-the-docs-writing-for-user-interfaces.json | 3 +-- ...rd-documenting-your-story-crafting-a-good-presentation.json | 3 +-- .../christina-elmore-all-roads-might-not-lead-to-docs.json | 3 +-- .../videos/diana-potter-screencasting-101.json | 3 +-- .../videos/elijah-caine-how-to-write-an-email.json | 3 +-- ...macallit-controlled-vocabularies-for-technical-writers.json | 3 +-- .../florian-scholz-jean-yves-perrier-gardening-open-docs.json | 3 +-- .../videos/jamie-hannaford-generating-docs-from-apis.json | 3 +-- ...the-future-what-can-documentarians-learn-from-the-past.json | 3 +-- ...atrick-keegan-free-your-mind-and-your-docs-will-follow.json | 3 +-- .../videos/paul-adams-judas-priest-ate-my-scrum-master.json | 3 +-- .../videos/paul-roeland-macgyvering-your-docs.json | 3 +-- ...matic-inclusive-tech-docs-techcomm-meets-accessibility.json | 3 +-- .../videos/riona-macnamara-imposter-no-more.json | 3 +-- .../videos/sonja-heinen-visual-documentation-language.json | 3 +-- .../videos/zdenek-nemec-writing-for-what-matters.json | 3 +-- 18 files changed, 18 insertions(+), 36 deletions(-) diff --git a/writethedocs-eu-2015/videos/adam-dangoor-tested-correct-how-to-make-sure-your-documentation-keeps-working.json b/writethedocs-eu-2015/videos/adam-dangoor-tested-correct-how-to-make-sure-your-documentation-keeps-working.json index f0a199ad1..59b16075f 100644 --- a/writethedocs-eu-2015/videos/adam-dangoor-tested-correct-how-to-make-sure-your-documentation-keeps-working.json +++ b/writethedocs-eu-2015/videos/adam-dangoor-tested-correct-how-to-make-sure-your-documentation-keeps-working.json @@ -1,7 +1,6 @@ { - "abstract": "When you are writing documentation for software, a top priority is\nsurely that what you write is correct. That is, the examples you provide\ngive the output you say they will. Or perhaps it is that the links in\nyour documentation link to an expected page. Usually this is done with\nmanual testing at the time of writing. Your organisation may have\npractices in place to make sure that these examples don't get too out of\ndate - maybe someone checks them periodically, maybe code review comes\nwith comments like \"I remember that this part of the code is used in an\nexample on Page 37 of our docs, change it\". But these methods are\ntedious and flawed. This talk will give examples from my work as a\nsoftware engineer in creating tested snippets for documentation which\nare linked to the code they represent. It will show how using techniques\ntraditionally reserved for software testing can ease the burden of\nkeeping documentation up to date.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "When you are writing documentation for software, a top priority is\nsurely that what you write is correct. That is, the examples you provide\ngive the output you say they will. Or perhaps it is that the links in\nyour documentation link to an expected page. Usually this is done with\nmanual testing at the time of writing. Your organisation may have\npractices in place to make sure that these examples don't get too out of\ndate - maybe someone checks them periodically, maybe code review comes\nwith comments like \"I remember that this part of the code is used in an\nexample on Page 37 of our docs, change it\". But these methods are\ntedious and flawed. This talk will give examples from my work as a\nsoftware engineer in creating tested snippets for documentation which\nare linked to the code they represent. It will show how using techniques\ntraditionally reserved for software testing can ease the burden of\nkeeping documentation up to date.\n", "duration": 1427, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/anna-jaruga-the-quest-for-scientific-credit-for-software-documentation.json b/writethedocs-eu-2015/videos/anna-jaruga-the-quest-for-scientific-credit-for-software-documentation.json index 17463095c..4dc919c3c 100644 --- a/writethedocs-eu-2015/videos/anna-jaruga-the-quest-for-scientific-credit-for-software-documentation.json +++ b/writethedocs-eu-2015/videos/anna-jaruga-the-quest-for-scientific-credit-for-software-documentation.json @@ -1,7 +1,6 @@ { - "abstract": "Modern geoscientific research relies heavily on numerical computations\ninvolving complex software developed by physicists or chemists. It would\nseem that scientists should be well versed in ways of documenting and\nexplaining their research. Yet, when it comes to the documentation of\nscientific software projects, one soon realises that scientific wisdom\nis spread mostly by LaTeX and that the word 'documentation' starts to\nmean something completely different.\n\nWriting a documentation for a scientific project can be quite\nchallenging. There are not that many examples of well-documented\nopen-source geoscientific numerical modelling software projects to drew\nthe inspiration from. Even though the scientific results should be\nreproducible, mechanisms that reward those who deliver well documented\nsoftware are still to become widespread. The scientists are judged\nbasing on the number of peer-reviewed papers they publish, therefore\ninvesting the time solely to offer the documentation is difficult. The\ndocumentation should include the actual mathematical equations and\ntheory behind the software, figures documenting the scientific results\nas well as code listings and usage examples. The target audience may\nhave a strong background in science, computer science, both or neither.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "Modern geoscientific research relies heavily on numerical computations\ninvolving complex software developed by physicists or chemists. It would\nseem that scientists should be well versed in ways of documenting and\nexplaining their research. Yet, when it comes to the documentation of\nscientific software projects, one soon realises that scientific wisdom\nis spread mostly by LaTeX and that the word 'documentation' starts to\nmean something completely different.\n\nWriting a documentation for a scientific project can be quite\nchallenging. There are not that many examples of well-documented\nopen-source geoscientific numerical modelling software projects to drew\nthe inspiration from. Even though the scientific results should be\nreproducible, mechanisms that reward those who deliver well documented\nsoftware are still to become widespread. The scientists are judged\nbasing on the number of peer-reviewed papers they publish, therefore\ninvesting the time solely to offer the documentation is difficult. The\ndocumentation should include the actual mathematical equations and\ntheory behind the software, figures documenting the scientific results\nas well as code listings and usage examples. The target audience may\nhave a strong background in science, computer science, both or neither.\n", "duration": 1454, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/beth-aitman-before-the-docs-writing-for-user-interfaces.json b/writethedocs-eu-2015/videos/beth-aitman-before-the-docs-writing-for-user-interfaces.json index bdd2f4c80..c96ef7197 100644 --- a/writethedocs-eu-2015/videos/beth-aitman-before-the-docs-writing-for-user-interfaces.json +++ b/writethedocs-eu-2015/videos/beth-aitman-before-the-docs-writing-for-user-interfaces.json @@ -1,7 +1,6 @@ { - "abstract": "Good documentation is important, but it should be your last resort. You\nneed to help users before they reach the docs - in the user interface\nitself.\n\nIn this talk, I'll discuss:\n\n- strategies for writing microcopy when you\u2019re short on space\n- what to explain in the UI, and what to save for the documentation\n- how to pick the right style of embedded help\n- what makes a great error message (and a terrible one)\n\n... with plenty of real-world examples of doing it right and wrong.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "Good documentation is important, but it should be your last resort. You\nneed to help users before they reach the docs - in the user interface\nitself.\n\nIn this talk, I'll discuss:\n\n- strategies for writing microcopy when you\u2019re short on space\n- what to explain in the UI, and what to save for the documentation\n- how to pick the right style of embedded help\n- what makes a great error message (and a terrible one)\n\n... with plenty of real-world examples of doing it right and wrong.\n", "duration": 1555, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/chris-ward-documenting-your-story-crafting-a-good-presentation.json b/writethedocs-eu-2015/videos/chris-ward-documenting-your-story-crafting-a-good-presentation.json index a4ad00eb1..748e0f133 100644 --- a/writethedocs-eu-2015/videos/chris-ward-documenting-your-story-crafting-a-good-presentation.json +++ b/writethedocs-eu-2015/videos/chris-ward-documenting-your-story-crafting-a-good-presentation.json @@ -1,7 +1,6 @@ { - "abstract": "Whilst not a part of the core documentation of projects, presentations\nand delivering them to the public are an essential part of spreading the\nword about what you do.\n\nThey need to be as equally consistent with your messaging and style\nguides, get to a key point effectively and also allow the presenter to\ninject some personality.\n\nThis is especially hard with technical projects where the 'story' is\neither hard to explain or can't just end up sounding like a sales pitch.\n\nIn this presentation I will explore and explain my experiences as an\nadvocate for several open source projects, audience reactions to those\npresentations and how I have iterated my presentations in sync with\nchanges to product and branding.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "Whilst not a part of the core documentation of projects, presentations\nand delivering them to the public are an essential part of spreading the\nword about what you do.\n\nThey need to be as equally consistent with your messaging and style\nguides, get to a key point effectively and also allow the presenter to\ninject some personality.\n\nThis is especially hard with technical projects where the 'story' is\neither hard to explain or can't just end up sounding like a sales pitch.\n\nIn this presentation I will explore and explain my experiences as an\nadvocate for several open source projects, audience reactions to those\npresentations and how I have iterated my presentations in sync with\nchanges to product and branding.\n", "duration": 713, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/christina-elmore-all-roads-might-not-lead-to-docs.json b/writethedocs-eu-2015/videos/christina-elmore-all-roads-might-not-lead-to-docs.json index d6914577c..fbb921726 100644 --- a/writethedocs-eu-2015/videos/christina-elmore-all-roads-might-not-lead-to-docs.json +++ b/writethedocs-eu-2015/videos/christina-elmore-all-roads-might-not-lead-to-docs.json @@ -1,7 +1,6 @@ { - "abstract": "Whilst not a part of the core documentation of projects, presentations\nand delivering them to the public are an essential part of spreading the\nword about what you do.\n\nThey need to be as equally consistent with your messaging and style\nguides, get to a key point effectively and also allow the presenter to\ninject some personality.\n\nThis is especially hard with technical projects where the 'story' is\neither hard to explain or can't just end up sounding like a sales pitch.\n\nIn this presentation I will explore and explain my experiences as an\nadvocate for several open source projects, audience reactions to those\npresentations and how I have iterated my presentations in sync with\nchanges to product and branding.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "Whilst not a part of the core documentation of projects, presentations\nand delivering them to the public are an essential part of spreading the\nword about what you do.\n\nThey need to be as equally consistent with your messaging and style\nguides, get to a key point effectively and also allow the presenter to\ninject some personality.\n\nThis is especially hard with technical projects where the 'story' is\neither hard to explain or can't just end up sounding like a sales pitch.\n\nIn this presentation I will explore and explain my experiences as an\nadvocate for several open source projects, audience reactions to those\npresentations and how I have iterated my presentations in sync with\nchanges to product and branding.\n", "duration": 1841, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/diana-potter-screencasting-101.json b/writethedocs-eu-2015/videos/diana-potter-screencasting-101.json index 0ab35514c..f7b8f97b3 100644 --- a/writethedocs-eu-2015/videos/diana-potter-screencasting-101.json +++ b/writethedocs-eu-2015/videos/diana-potter-screencasting-101.json @@ -1,7 +1,6 @@ { - "abstract": "As a writer, it's been tough for me to admit that not everyone wants to\nread my carefully written documentation. While people will read, not\neveryone learns by reading the docs. Since my goal is to make sure my\ndocumentation can meet as many learning styles as possible, that has\nmeant spreading my documentarian wings and bridging out from only\nwriting the docs into recording them as well.\n\nPart of my documentation journey has been learning how to create\nscreencasts and I want to share that knowledge with everyone. From\npicking the right topics, to outlining, to writing a script (yes I\npromise, there is still writing involved), to how to record your audio\nand video, I'll cover it all. You don't need to be a professional voice\nactor or videographer to create a screencast, even a writer can create\nsomething wonderful.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "As a writer, it's been tough for me to admit that not everyone wants to\nread my carefully written documentation. While people will read, not\neveryone learns by reading the docs. Since my goal is to make sure my\ndocumentation can meet as many learning styles as possible, that has\nmeant spreading my documentarian wings and bridging out from only\nwriting the docs into recording them as well.\n\nPart of my documentation journey has been learning how to create\nscreencasts and I want to share that knowledge with everyone. From\npicking the right topics, to outlining, to writing a script (yes I\npromise, there is still writing involved), to how to record your audio\nand video, I'll cover it all. You don't need to be a professional voice\nactor or videographer to create a screencast, even a writer can create\nsomething wonderful.\n", "duration": 633, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/elijah-caine-how-to-write-an-email.json b/writethedocs-eu-2015/videos/elijah-caine-how-to-write-an-email.json index 7c1b36793..946aa0374 100644 --- a/writethedocs-eu-2015/videos/elijah-caine-how-to-write-an-email.json +++ b/writethedocs-eu-2015/videos/elijah-caine-how-to-write-an-email.json @@ -1,7 +1,6 @@ { - "abstract": "Nobody loves email. Nobody really even likes email. In fact email can\ntotally suck and it is here to stay. Despite how we feel about it, we\nhave to deal with email almost every single day. Fortunately we can\nimprove email as a whole by learning how to write email that sucks just\na little bit less -- not that you write bad emails.. this talk is for\nyour... friend. Yeah, this talk is for your friends that really need to\nsetup up their email game.\n\nIn addition to email this talk will explore some fundamental\nmisunderstandings that people have with modes of online communication\nand how to correct these misunderstandings. Like how to craft a good\nTweet, Facebook Post, and Instant Messaging interaction.\n\nThis is not meant to be a tutorial but rather a conceptual guide for how\nto think about on-line communication and how to correct some common\nfaults we share as members of the on-line community. The Internet isn't\ngoing away anytime soon, and the amount we communicate over it is not\ngoing to diminish anytime soon either. This talk attempts to teach one\nhow to make digital communication as painless as possible.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "Nobody loves email. Nobody really even likes email. In fact email can\ntotally suck and it is here to stay. Despite how we feel about it, we\nhave to deal with email almost every single day. Fortunately we can\nimprove email as a whole by learning how to write email that sucks just\na little bit less -- not that you write bad emails.. this talk is for\nyour... friend. Yeah, this talk is for your friends that really need to\nsetup up their email game.\n\nIn addition to email this talk will explore some fundamental\nmisunderstandings that people have with modes of online communication\nand how to correct these misunderstandings. Like how to craft a good\nTweet, Facebook Post, and Instant Messaging interaction.\n\nThis is not meant to be a tutorial but rather a conceptual guide for how\nto think about on-line communication and how to correct some common\nfaults we share as members of the on-line community. The Internet isn't\ngoing away anytime soon, and the amount we communicate over it is not\ngoing to diminish anytime soon either. This talk attempts to teach one\nhow to make digital communication as painless as possible.\n", "duration": 1654, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/emilie-boillat-whatchamacallit-controlled-vocabularies-for-technical-writers.json b/writethedocs-eu-2015/videos/emilie-boillat-whatchamacallit-controlled-vocabularies-for-technical-writers.json index e730c5058..93ce2eaa8 100644 --- a/writethedocs-eu-2015/videos/emilie-boillat-whatchamacallit-controlled-vocabularies-for-technical-writers.json +++ b/writethedocs-eu-2015/videos/emilie-boillat-whatchamacallit-controlled-vocabularies-for-technical-writers.json @@ -1,7 +1,6 @@ { - "abstract": "An everyday dilemma in technical communication: What do you call that\n\u201cthing\u201d? Whether you ask developers, marketing folks or users, you often\nget very different views.\n\nAlong with user interfaces, documentation helps all stakeholders align\ntheir mental model of a product. Terminology plays a key role, and a\ncontrolled vocabulary is an ace up the technical writer's sleeve.\n\nControlled vocabularies are basically lists of concepts and the\nrelationships between them. Beyond consistent naming, they are about\nstructuring, categorizing and retrieving content. For example, you can\nuse a vocabulary as a basis for documentation plans, tables of content,\na help site's navigation, search filters, or even to organize test\ncases.\n\nIn this talk, I will share ways to create and maintain various types of\nvocabularies, and explain what each type is useful for. You can start\nwith a flat list of terms and expand it into a glossary, a thesaurus, a\ntaxonomy, or even a full-fledge ontology.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "An everyday dilemma in technical communication: What do you call that\n\u201cthing\u201d? Whether you ask developers, marketing folks or users, you often\nget very different views.\n\nAlong with user interfaces, documentation helps all stakeholders align\ntheir mental model of a product. Terminology plays a key role, and a\ncontrolled vocabulary is an ace up the technical writer's sleeve.\n\nControlled vocabularies are basically lists of concepts and the\nrelationships between them. Beyond consistent naming, they are about\nstructuring, categorizing and retrieving content. For example, you can\nuse a vocabulary as a basis for documentation plans, tables of content,\na help site's navigation, search filters, or even to organize test\ncases.\n\nIn this talk, I will share ways to create and maintain various types of\nvocabularies, and explain what each type is useful for. You can start\nwith a flat list of terms and expand it into a glossary, a thesaurus, a\ntaxonomy, or even a full-fledge ontology.\n", "duration": 1885, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/florian-scholz-jean-yves-perrier-gardening-open-docs.json b/writethedocs-eu-2015/videos/florian-scholz-jean-yves-perrier-gardening-open-docs.json index 08a0dfe03..f7501f668 100644 --- a/writethedocs-eu-2015/videos/florian-scholz-jean-yves-perrier-gardening-open-docs.json +++ b/writethedocs-eu-2015/videos/florian-scholz-jean-yves-perrier-gardening-open-docs.json @@ -1,7 +1,6 @@ { - "abstract": "With about 1000 different editors each month, the Mozilla Developer\nNetwork (MDN) documentation Web site for Open Web technologies is a\ntrafficked wiki with edits of all kind of quality: perfect text from\nseasoned professional writers to rough notes by teen-aged technology\nlearners.\n\nIn this talk, we are going to explore how to keep this doc garden clean,\nhow the diversity of editors influence its evolution, and how we find\nour way through treacherous jungles to well-maintained royal gardens.\n\nThis is about improving quality, working with diverse communities,\nfostering innovation, and carnivorous plants.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "With about 1000 different editors each month, the Mozilla Developer\nNetwork (MDN) documentation Web site for Open Web technologies is a\ntrafficked wiki with edits of all kind of quality: perfect text from\nseasoned professional writers to rough notes by teen-aged technology\nlearners.\n\nIn this talk, we are going to explore how to keep this doc garden clean,\nhow the diversity of editors influence its evolution, and how we find\nour way through treacherous jungles to well-maintained royal gardens.\n\nThis is about improving quality, working with diverse communities,\nfostering innovation, and carnivorous plants.\n", "duration": 1570, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/jamie-hannaford-generating-docs-from-apis.json b/writethedocs-eu-2015/videos/jamie-hannaford-generating-docs-from-apis.json index c8e6f821d..6f5f5792f 100644 --- a/writethedocs-eu-2015/videos/jamie-hannaford-generating-docs-from-apis.json +++ b/writethedocs-eu-2015/videos/jamie-hannaford-generating-docs-from-apis.json @@ -1,7 +1,6 @@ { - "abstract": "APIs define contracts between a service and a client, and with the rise\nof representation languages like Swagger, Apiary, and RAML, these\ncontracts can be consumed programmatically and adapted easily into our\ncodebases. Other tools like JSON Schema also contribute to this idea of\nintegration between service and client.\n\nBut what about our documentation? If API contracts can be assimilated\ninto software, surely it can drive our documentation too? In this talk,\nI want to introduce some of the techniques I've used on past projects\nthat allow exactly that. By using remote schemas to generate software,\nit also allows us to generate working documentation that is always\nrelevant and never out of date. Apart from accuracy, we also get the\nadded benefits of reduced development time, reduced effort, and reduced\nduplication. We can all of this by documenting once, and re-using across\nmultiple projects!\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "APIs define contracts between a service and a client, and with the rise\nof representation languages like Swagger, Apiary, and RAML, these\ncontracts can be consumed programmatically and adapted easily into our\ncodebases. Other tools like JSON Schema also contribute to this idea of\nintegration between service and client.\n\nBut what about our documentation? If API contracts can be assimilated\ninto software, surely it can drive our documentation too? In this talk,\nI want to introduce some of the techniques I've used on past projects\nthat allow exactly that. By using remote schemas to generate software,\nit also allows us to generate working documentation that is always\nrelevant and never out of date. Apart from accuracy, we also get the\nadded benefits of reduced development time, reduced effort, and reduced\nduplication. We can all of this by documenting once, and re-using across\nmultiple projects!\n", "duration": 1795, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/jennifer-rondeau-back-to-the-future-what-can-documentarians-learn-from-the-past.json b/writethedocs-eu-2015/videos/jennifer-rondeau-back-to-the-future-what-can-documentarians-learn-from-the-past.json index ccb76a5f2..d69661f69 100644 --- a/writethedocs-eu-2015/videos/jennifer-rondeau-back-to-the-future-what-can-documentarians-learn-from-the-past.json +++ b/writethedocs-eu-2015/videos/jennifer-rondeau-back-to-the-future-what-can-documentarians-learn-from-the-past.json @@ -1,7 +1,6 @@ { - "abstract": "The world of software development rightly demands an emphasis on the new\nand the innovative -- on doing things differently from how they\u2019ve been\ndone. The assumption is that newer is (almost) always better. But if we\nlook only to the present and the future, we risk reinventing the wheel,\nfailing to understand that we are all built on tradition, failing to\nlearn everything that we could from the past.\n\nThis talk shows how documentarians can find inspiration in the past,\nbuild on it, and move forward. It tells some of these stories, and shows\nwhat they meant in historical context:\n\n- The pre-history and dawn of software documentation -- how technical\n writers were hired, how they worked, what they made, the challenges\n they faced, and how their solutions continue to inform the work we do\n today\n- The much longer history of teaching engineers to write documentation\n- Efforts to make technical writing into an independent profession\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "The world of software development rightly demands an emphasis on the new\nand the innovative -- on doing things differently from how they\u2019ve been\ndone. The assumption is that newer is (almost) always better. But if we\nlook only to the present and the future, we risk reinventing the wheel,\nfailing to understand that we are all built on tradition, failing to\nlearn everything that we could from the past.\n\nThis talk shows how documentarians can find inspiration in the past,\nbuild on it, and move forward. It tells some of these stories, and shows\nwhat they meant in historical context:\n\n- The pre-history and dawn of software documentation -- how technical\n writers were hired, how they worked, what they made, the challenges\n they faced, and how their solutions continue to inform the work we do\n today\n- The much longer history of teaching engineers to write documentation\n- Efforts to make technical writing into an independent profession\n", "duration": 1886, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/patrick-keegan-free-your-mind-and-your-docs-will-follow.json b/writethedocs-eu-2015/videos/patrick-keegan-free-your-mind-and-your-docs-will-follow.json index 79a3e6c54..6dab8e162 100644 --- a/writethedocs-eu-2015/videos/patrick-keegan-free-your-mind-and-your-docs-will-follow.json +++ b/writethedocs-eu-2015/videos/patrick-keegan-free-your-mind-and-your-docs-will-follow.json @@ -1,7 +1,6 @@ { - "abstract": "As documentarians, we face plenty of hurdles to delivering what we are\nassigned (harried and inaccessible subject matter experts, barely\nfunctioning builds, sketchy doc infrastructure, etc.). But there are\nalso the obstacles that keep us from writing the docs we *want*, and\nthose are largely ingrained in our companies' processes and our own\nheads.\n\nWe pay lip service to \"the user\" but then subordinate that to concerns\nof structure, consistency, and stylistic conventions. The result is\noften docs that are internally consistent and satisfy the editorial,\ntranslation, and production teams for their economy and re-usability but\nare so dry and product-centered that they fail to connect with the most\nimportant audience - actual human beings.\n\nIn this presentation, I'll talk about ways to overcome burdensome\norganizational processes and our own timidity to create room for the\ninspiration and creativity needed to bring the docs' subject alive.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "As documentarians, we face plenty of hurdles to delivering what we are\nassigned (harried and inaccessible subject matter experts, barely\nfunctioning builds, sketchy doc infrastructure, etc.). But there are\nalso the obstacles that keep us from writing the docs we *want*, and\nthose are largely ingrained in our companies' processes and our own\nheads.\n\nWe pay lip service to \"the user\" but then subordinate that to concerns\nof structure, consistency, and stylistic conventions. The result is\noften docs that are internally consistent and satisfy the editorial,\ntranslation, and production teams for their economy and re-usability but\nare so dry and product-centered that they fail to connect with the most\nimportant audience - actual human beings.\n\nIn this presentation, I'll talk about ways to overcome burdensome\norganizational processes and our own timidity to create room for the\ninspiration and creativity needed to bring the docs' subject alive.\n", "duration": 933, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/paul-adams-judas-priest-ate-my-scrum-master.json b/writethedocs-eu-2015/videos/paul-adams-judas-priest-ate-my-scrum-master.json index 8371ab04e..a3ce8f8bd 100644 --- a/writethedocs-eu-2015/videos/paul-adams-judas-priest-ate-my-scrum-master.json +++ b/writethedocs-eu-2015/videos/paul-adams-judas-priest-ate-my-scrum-master.json @@ -1,7 +1,6 @@ { - "abstract": "Community Management in Free Software communities is still an emerging\nfield and has produced a spectrum of practitioners: from\nmaster-manipulators of social media, to those more focused on metrics\nand data as a means to driving process. Either way, the state of the art\nis still largely driven by the needs of technical contributors to\nprojects.\n\nGood documentation is a crucial component in a software product and yet\noften technical writers are overlooked as important stakeholders of the\nprocess. Within the community, there are undoubtedly common problems\nbetween engineers and technical writers. Software Engineering is full of\nlaws; can we show that these laws apply to technical writers as a means\nto help bridge the chasm between developers and technical writers??\n\nIn this talk Paul walks us through a selection of his favourite laws of\nsoftware engineering and explores how developers measure them and if\ntechnical writers must also obey them. Or not. And what that means for\nthe success of documentation in a Free Software project.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "Community Management in Free Software communities is still an emerging\nfield and has produced a spectrum of practitioners: from\nmaster-manipulators of social media, to those more focused on metrics\nand data as a means to driving process. Either way, the state of the art\nis still largely driven by the needs of technical contributors to\nprojects.\n\nGood documentation is a crucial component in a software product and yet\noften technical writers are overlooked as important stakeholders of the\nprocess. Within the community, there are undoubtedly common problems\nbetween engineers and technical writers. Software Engineering is full of\nlaws; can we show that these laws apply to technical writers as a means\nto help bridge the chasm between developers and technical writers??\n\nIn this talk Paul walks us through a selection of his favourite laws of\nsoftware engineering and explores how developers measure them and if\ntechnical writers must also obey them. Or not. And what that means for\nthe success of documentation in a Free Software project.\n", "duration": 1788, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/paul-roeland-macgyvering-your-docs.json b/writethedocs-eu-2015/videos/paul-roeland-macgyvering-your-docs.json index 36111b9df..f44c18534 100644 --- a/writethedocs-eu-2015/videos/paul-roeland-macgyvering-your-docs.json +++ b/writethedocs-eu-2015/videos/paul-roeland-macgyvering-your-docs.json @@ -1,7 +1,6 @@ { - "abstract": "\"So, your project needs better docs. For that, you'd need lots of\npeople. Professionalism. A well-thought out plan. All the tools. And a\nwhopping budget in both time and money.\n\nInstead, you're sitting there, with just a few paperclips, seven moldy\nMentos mints, a strip of Duct tape, a pencil and some nail polish\nremover...\n\nOh, hang on! There's also the combined experiences of generations of\npeople fighting seemingly insurmountable odds. From environmental\nactivists to LGBTQ people taking to the streets, we can draw on a rich\nhistory of inspired individuals taking whatever is at hand, mixed with\nsome clever zaniness to quite fabulous effect.\n\nSo, what if we apply an activist mindset and some DIY hacking into our\nprocess? What lessons can we learn from a world where TOC means Theory\nOf Change, where working on a shoestring budget is the norm and where\nempowering people to go beyond what they think they can do is considered\nmission- critical?\n\nTo be clear: the aim here is not to knock professionalism in docs, quite\nthe contrary! Yet, faced with a lack of resources, 'bend the rules and\nget going' sure beats lethargy. Not to mention being fun...\n\n(And before you think I'll be bringing back the dreaded mullet: the next\nMacGyver will be a woman, according to http://thenextmacgyver.com)\"\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "\"So, your project needs better docs. For that, you'd need lots of\npeople. Professionalism. A well-thought out plan. All the tools. And a\nwhopping budget in both time and money.\n\nInstead, you're sitting there, with just a few paperclips, seven moldy\nMentos mints, a strip of Duct tape, a pencil and some nail polish\nremover...\n\nOh, hang on! There's also the combined experiences of generations of\npeople fighting seemingly insurmountable odds. From environmental\nactivists to LGBTQ people taking to the streets, we can draw on a rich\nhistory of inspired individuals taking whatever is at hand, mixed with\nsome clever zaniness to quite fabulous effect.\n\nSo, what if we apply an activist mindset and some DIY hacking into our\nprocess? What lessons can we learn from a world where TOC means Theory\nOf Change, where working on a shoestring budget is the norm and where\nempowering people to go beyond what they think they can do is considered\nmission- critical?\n\nTo be clear: the aim here is not to knock professionalism in docs, quite\nthe contrary! Yet, faced with a lack of resources, 'bend the rules and\nget going' sure beats lethargy. Not to mention being fun...\n\n(And before you think I'll be bringing back the dreaded mullet: the next\nMacGyver will be a woman, according to http://thenextmacgyver.com)\"\n", "duration": 1845, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/radina-matic-inclusive-tech-docs-techcomm-meets-accessibility.json b/writethedocs-eu-2015/videos/radina-matic-inclusive-tech-docs-techcomm-meets-accessibility.json index e022f94c5..370827bc8 100644 --- a/writethedocs-eu-2015/videos/radina-matic-inclusive-tech-docs-techcomm-meets-accessibility.json +++ b/writethedocs-eu-2015/videos/radina-matic-inclusive-tech-docs-techcomm-meets-accessibility.json @@ -1,7 +1,6 @@ { - "abstract": "Presenting a business case for quality documentation can sometimes be a\ndifficult enough task. Adding to that the accessibility requirements,\nand the whole idea may resemble a mission impossible. The fact that\nofficial standards (WCAG and WAI-ARIA) themselves seem to require user\nmanuals in order to be properly implemented, is not helping developers,\ntechnical communicators and content managers achieve the desired\nresults. This talk will present the main points and a selection of tools\nto get through the labyrinth of WCAG techniques and guidelines, and help\nyou make your techcomm project accessibility-ready. Welcome to A11y for\nTech Docs!\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "Presenting a business case for quality documentation can sometimes be a\ndifficult enough task. Adding to that the accessibility requirements,\nand the whole idea may resemble a mission impossible. The fact that\nofficial standards (WCAG and WAI-ARIA) themselves seem to require user\nmanuals in order to be properly implemented, is not helping developers,\ntechnical communicators and content managers achieve the desired\nresults. This talk will present the main points and a selection of tools\nto get through the labyrinth of WCAG techniques and guidelines, and help\nyou make your techcomm project accessibility-ready. Welcome to A11y for\nTech Docs!\n", "duration": 1880, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/riona-macnamara-imposter-no-more.json b/writethedocs-eu-2015/videos/riona-macnamara-imposter-no-more.json index ea91354cf..302fea48c 100644 --- a/writethedocs-eu-2015/videos/riona-macnamara-imposter-no-more.json +++ b/writethedocs-eu-2015/videos/riona-macnamara-imposter-no-more.json @@ -1,7 +1,6 @@ { - "abstract": "Do you feel like a fraud? Do you have that sneaking fear of being \u201cfound\nout\u201d and exposed? Imposter syndrome is corrosive. It holds us back at\nwork - especially in an industry where we can feel constantly under\nreview by talented peers - and erodes our happiness. And the subject\nalways comes up whenever technical writers gather; sometimes it feels\nlike the very definition of a technical writer is \u201cOne who experiences\nimposter syndrome.\u201d\n\nWhy is this? The first, shorter part of this talk will cover some\nresearch and insights into why we, as documentarians, may be especially\nsusceptible to imposter syndrome.\n\nBut the field of tech writing is experiencing a swerve: a tipping point\n- a sea change in direction. There will always be a demand for \"\"old\"\"\ntech writing, but many of us will have to adapt to this new environment.\n\nIn the second, forward-looking part of this talk, I\u2019ll argue that being\nan \u201cimposter\u201d has its advantages during such a time of change. The very\nfactors that contribute to our self-doubt are actually the qualities\nthat will enable us to thrive as our role inexorably evolves to take on\nnew, unsolved challenges in engineering information. The keys to our\nsuccess: apophenia (the ability to see connections between seemingly\nrandom collections of information), empathy, and adaptability.\n\nOur future is bright if we pay attention to our new opportunities\ninstead of that nagging voice in our heads.\n", "copyright_text": null, - "description": "... How Tech Writers Can Shed Self-Doubt, Embrace Uncertainty, and Surf the Upcoming Swerve in Technical Documentation\n\nFull talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "Do you feel like a fraud? Do you have that sneaking fear of being \u201cfound\nout\u201d and exposed? Imposter syndrome is corrosive. It holds us back at\nwork - especially in an industry where we can feel constantly under\nreview by talented peers - and erodes our happiness. And the subject\nalways comes up whenever technical writers gather; sometimes it feels\nlike the very definition of a technical writer is \u201cOne who experiences\nimposter syndrome.\u201d\n\nWhy is this? The first, shorter part of this talk will cover some\nresearch and insights into why we, as documentarians, may be especially\nsusceptible to imposter syndrome.\n\nBut the field of tech writing is experiencing a swerve: a tipping point\n- a sea change in direction. There will always be a demand for \"\"old\"\"\ntech writing, but many of us will have to adapt to this new environment.\n\nIn the second, forward-looking part of this talk, I\u2019ll argue that being\nan \u201cimposter\u201d has its advantages during such a time of change. The very\nfactors that contribute to our self-doubt are actually the qualities\nthat will enable us to thrive as our role inexorably evolves to take on\nnew, unsolved challenges in engineering information. The keys to our\nsuccess: apophenia (the ability to see connections between seemingly\nrandom collections of information), empathy, and adaptability.\n\nOur future is bright if we pay attention to our new opportunities\ninstead of that nagging voice in our heads.\n", "duration": 1853, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/sonja-heinen-visual-documentation-language.json b/writethedocs-eu-2015/videos/sonja-heinen-visual-documentation-language.json index e6d9938b1..b427b6d77 100644 --- a/writethedocs-eu-2015/videos/sonja-heinen-visual-documentation-language.json +++ b/writethedocs-eu-2015/videos/sonja-heinen-visual-documentation-language.json @@ -1,7 +1,6 @@ { - "abstract": "A picture says more than \u2026how many lines of code?\n\nFirstly this talk offers an introduction to a variety of established as\nwell as experimental visual documentation methods. Subsequently, it\nexplores the question whether or not these approaches can be applied to\nsoftware documentation in a reasonable way.\n\nIn this regard it takes a closer look at individual methods and\nestimates their corresponding affordances in terms of time, skill,\nresources and potential automatization.\n\nEventually, this talk presents an initial attempt to translate existing\ndocs into visual languages and discusses the according outcomes.\n\nPrimarily, the objective of reading and writing the docs serves the\npurpose to convey clear, unambiguous information, at the same time, the\nexperience should be as engaging and pleasant as possible. Building a\nVisual Documentation Language serves to reach this goal.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "A picture says more than \u2026how many lines of code?\n\nFirstly this talk offers an introduction to a variety of established as\nwell as experimental visual documentation methods. Subsequently, it\nexplores the question whether or not these approaches can be applied to\nsoftware documentation in a reasonable way.\n\nIn this regard it takes a closer look at individual methods and\nestimates their corresponding affordances in terms of time, skill,\nresources and potential automatization.\n\nEventually, this talk presents an initial attempt to translate existing\ndocs into visual languages and discusses the according outcomes.\n\nPrimarily, the objective of reading and writing the docs serves the\npurpose to convey clear, unambiguous information, at the same time, the\nexperience should be as engaging and pleasant as possible. Building a\nVisual Documentation Language serves to reach this goal.\n", "duration": 1615, "language": "eng", "recorded": "2015-08-31", diff --git a/writethedocs-eu-2015/videos/zdenek-nemec-writing-for-what-matters.json b/writethedocs-eu-2015/videos/zdenek-nemec-writing-for-what-matters.json index 3c8aed94e..712634d5c 100644 --- a/writethedocs-eu-2015/videos/zdenek-nemec-writing-for-what-matters.json +++ b/writethedocs-eu-2015/videos/zdenek-nemec-writing-for-what-matters.json @@ -1,7 +1,6 @@ { - "abstract": "Most of the documentation we read today puts a lot of burden on us\nbefore we have the chance to get to the gist. Abstract and clear\nconcepts are replaced by concrete and comprehensive ones. The real\nvalues are hindered by opaque clouds of facts about tools of trade. As a\nresult, thinking and imagination are suppressed.\n\nBut what if we can write documentation that encourages thinking?\n\nLet's look together on what really matters when documenting computer\nsystems. We will discuss how a documentation and system design can walk\nhand in hand and to improve the communication between both humans and\nmachines.\n", "copyright_text": null, - "description": "Full talk description: http://www.writethedocs.org/conf/eu/2015/speakers/\n\nSlides: http://www.writethedocs.org/conf/eu/2015/schedule/\n\nFollow us on Twitter @writethedocs\n\nJoin our mailing list http://writethedocs.us11.list-manage.com/subscribe?u=fcfe905987123983cc93c7a46&id=e2e27d6167", + "description": "Most of the documentation we read today puts a lot of burden on us\nbefore we have the chance to get to the gist. Abstract and clear\nconcepts are replaced by concrete and comprehensive ones. The real\nvalues are hindered by opaque clouds of facts about tools of trade. As a\nresult, thinking and imagination are suppressed.\n\nBut what if we can write documentation that encourages thinking?\n\nLet's look together on what really matters when documenting computer\nsystems. We will discuss how a documentation and system design can walk\nhand in hand and to improve the communication between both humans and\nmachines.\n", "duration": 934, "language": "eng", "recorded": "2015-08-31",