From 111776bc8851325cc2225d78b7f11053d86ffd7e Mon Sep 17 00:00:00 2001 From: Jon Banafato Date: Mon, 29 Jul 2024 16:14:57 -0400 Subject: [PATCH] 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",