When you are writing documentation for software, a top priority is surely that what you write is correct. That is, the examples you provide give the output you say they will. Or perhaps it is that the links in your documentation link to an expected page. Usually this is done with manual testing at the time of writing. Your organisation may have practices in place to make sure that these examples don't get too out of date - maybe someone checks them periodically, maybe code review comes with comments like "I remember that this part of the code is used in an example on Page 37 of our docs, change it". But these methods are tedious and flawed. This talk will give examples from my work as a software engineer in creating tested snippets for documentation which are linked to the code they represent. It will show how using techniques traditionally reserved for software testing can ease the burden of keeping documentation up to date. </p>
Modern geoscientific research relies heavily on numerical computations involving complex software developed by physicists or chemists. It would seem that scientists should be well versed in ways of documenting and explaining their research. Yet, when it comes to the documentation of scientific software projects, one soon realises that scientific wisdom is spread mostly by LaTeX and that the word 'documentation' starts to mean something completely different. </p> <p>Writing a documentation for a scientific project can be quite challenging. There are not that many examples of well-documented open-source geoscientific numerical modelling software projects to drew the inspiration from. Even though the scientific results should be reproducible, mechanisms that reward those who deliver well documented software are still to become widespread. The scientists are judged basing on the number of peer-reviewed papers they publish, therefore investing the time solely to offer the documentation is difficult. The documentation should include the actual mathematical equations and theory behind the software, figures documenting the scientific results as well as code listings and usage examples. The target audience may have a strong background in science, computer science, both or neither. </p>
Good documentation is important, but it should be your last resort. You need to help users before they reach the docs - in the user interface itself.</p> <p>In this talk, I'll discuss:</p> <ul> <li>strategies for writing microcopy when you’re short on space</li> <li>what to explain in the UI, and what to save for the documentation</li> <li>how to pick the right style of embedded help</li> <li>what makes a great error message (and a terrible one)</li> </ul> <p>... with plenty of real-world examples of doing it right and wrong.</p>
Whilst not a part of the core documentation of projects, presentations and delivering them to the public are an essential part of spreading the word about what you do.</p> <p>They need to be as equally consistent with your messaging and style guides, get to a key point effectively and also allow the presenter to inject some personality.</p> <p>This is especially hard with technical projects where the 'story' is either hard to explain or can't just end up sounding like a sales pitch.</p> <p>In this presentation I will explore and explain my experiences as an advocate for several open source projects, audience reactions to those presentations and how I have iterated my presentations in sync with changes to product and branding.</p>
Documentation may not have a reputation as a creative enterprise, but we know that filling the role of documentarian requires creative problem solving - especially in figuring how to create, display, and maintain a reliable collection of docs.</p> <p>If your goal is clear - we need (better) docs - then creativity comes in discovering how to get there. But creative problem solving has an important role to play in determining whether you've got the right goal: are docs the answer?</p> <p>This talk starts with framing the common types of needs that docs can meet: informing, learning, referencing, persuading, and engaging. With examples for each, we'll see how creative thinking - mixed with data and some knowledge of human behavior - can shape problem statements that lead to better solutions, which aren't always the traditional doc. It's about making sure that we, as documentarians, aren't just writing - we're shaping the discussion about when and how docs make our teams, organizations, and communities better.</p>
As a writer, it's been tough for me to admit that not everyone wants to read my carefully written documentation. While people will read, not everyone learns by reading the docs. Since my goal is to make sure my documentation can meet as many learning styles as possible, that has meant spreading my documentarian wings and bridging out from only writing the docs into recording them as well.</p> <p>Part of my documentation journey has been learning how to create screencasts and I want to share that knowledge with everyone. From picking the right topics, to outlining, to writing a script (yes I promise, there is still writing involved), to how to record your audio and video, I'll cover it all. You don't need to be a professional voice actor or videographer to create a screencast, even a writer can create something wonderful.</p>
Nobody loves email. Nobody really even likes email. In fact email can totally suck and it is here to stay. Despite how we feel about it, we have to deal with email almost every single day. Fortunately we can improve email as a whole by learning how to write email that sucks just a little bit less -- not that you write bad emails.. this talk is for your... friend. Yeah, this talk is for your friends that really need to setup up their email game.</p> <p>In addition to email this talk will explore some fundamental misunderstandings that people have with modes of online communication and how to correct these misunderstandings. Like how to craft a good Tweet, Facebook Post, and Instant Messaging interaction.</p> <p>This is not meant to be a tutorial but rather a conceptual guide for how to think about on-line communication and how to correct some common faults we share as members of the on-line community. The Internet isn't going away anytime soon, and the amount we communicate over it is not going to diminish anytime soon either. This talk attempts to teach one how to make digital communication as painless as possible.</p>
An everyday dilemma in technical communication: What do you call that “thing”? Whether you ask developers, marketing folks or users, you often get very different views.</p> <p>Along with user interfaces, documentation helps all stakeholders align their mental model of a product. Terminology plays a key role, and a controlled vocabulary is an ace up the technical writer's sleeve.</p> <p>Controlled vocabularies are basically lists of concepts and the relationships between them. Beyond consistent naming, they are about structuring, categorizing and retrieving content. For example, you can use a vocabulary as a basis for documentation plans, tables of content, a help site's navigation, search filters, or even to organize test cases.</p> <p>In this talk, I will share ways to create and maintain various types of vocabularies, and explain what each type is useful for. You can start with a flat list of terms and expand it into a glossary, a thesaurus, a taxonomy, or even a full-fledge ontology.</p>
With about 1000 different editors each month, the Mozilla Developer Network (MDN) documentation Web site for Open Web technologies is a trafficked wiki with edits of all kind of quality: perfect text from seasoned professional writers to rough notes by teen-aged technology learners.</p> <p>In this talk, we are going to explore how to keep this doc garden clean, how the diversity of editors influence its evolution, and how we find our way through treacherous jungles to well-maintained royal gardens.</p> <p>This is about improving quality, working with diverse communities, fostering innovation, and carnivorous plants.</p>
APIs define contracts between a service and a client, and with the rise of representation languages like Swagger, Apiary, and RAML, these contracts can be consumed programmatically and adapted easily into our codebases. Other tools like JSON Schema also contribute to this idea of integration between service and client.</p> <p>But what about our documentation? If API contracts can be assimilated into software, surely it can drive our documentation too? In this talk, I want to introduce some of the techniques I've used on past projects that allow exactly that. By using remote schemas to generate software, it also allows us to generate working documentation that is always relevant and never out of date. Apart from accuracy, we also get the added benefits of reduced development time, reduced effort, and reduced duplication. We can all of this by documenting once, and re-using across multiple projects!</p>
The world of software development rightly demands an emphasis on the new and the innovative -- on doing things differently from how they’ve been done. The assumption is that newer is (almost) always better. But if we look only to the present and the future, we risk reinventing the wheel, failing to understand that we are all built on tradition, failing to learn everything that we could from the past.</p> <p>This talk shows how documentarians can find inspiration in the past, build on it, and move forward. It tells some of these stories, and shows what they meant in historical context:</p> <ul> <li>The pre-history and dawn of software documentation -- how technical writers were hired, how they worked, what they made, the challenges they faced, and how their solutions continue to inform the work we do today</li> <li>The much longer history of teaching engineers to write documentation</li> <li>Efforts to make technical writing into an independent profession</li> </ul>
As documentarians, we face plenty of hurdles to delivering what we are assigned (harried and inaccessible subject matter experts, barely functioning builds, sketchy doc infrastructure, etc.). But there are also the obstacles that keep us from writing the docs we *want*, and those are largely ingrained in our companies' processes and our own heads.</p> <p>We pay lip service to "the user" but then subordinate that to concerns of structure, consistency, and stylistic conventions. The result is often docs that are internally consistent and satisfy the editorial, translation, and production teams for their economy and re-usability but are so dry and product-centered that they fail to connect with the most important audience - actual human beings.</p> <p>In this presentation, I'll talk about ways to overcome burdensome organizational processes and our own timidity to create room for the inspiration and creativity needed to bring the docs' subject alive.</p>
Community Management in Free Software communities is still an emerging field and has produced a spectrum of practitioners: from master-manipulators of social media, to those more focused on metrics and data as a means to driving process. Either way, the state of the art is still largely driven by the needs of technical contributors to projects.</p> <p>Good documentation is a crucial component in a software product and yet often technical writers are overlooked as important stakeholders of the process. Within the community, there are undoubtedly common problems between engineers and technical writers. Software Engineering is full of laws; can we show that these laws apply to technical writers as a means to help bridge the chasm between developers and technical writers??</p> <p>In this talk Paul walks us through a selection of his favourite laws of software engineering and explores how developers measure them and if technical writers must also obey them. Or not. And what that means for the success of documentation in a Free Software project.</p>
"So, your project needs better docs. For that, you'd need lots of people. Professionalism. A well-thought out plan. All the tools. And a whopping budget in both time and money.</p> <p>Instead, you're sitting there, with just a few paperclips, seven moldy Mentos mints, a strip of Duct tape, a pencil and some nail polish remover...</p> <p>Oh, hang on! There's also the combined experiences of generations of people fighting seemingly insurmountable odds. From environmental activists to LGBTQ people taking to the streets, we can draw on a rich history of inspired individuals taking whatever is at hand, mixed with some clever zaniness to quite fabulous effect.</p> <p>So, what if we apply an activist mindset and some DIY hacking into our process? What lessons can we learn from a world where TOC means Theory Of Change, where working on a shoestring budget is the norm and where empowering people to go beyond what they think they can do is considered mission-critical?</p> <p>To be clear: the aim here is not to knock professionalism in docs, quite the contrary! Yet, faced with a lack of resources, 'bend the rules and get going' sure beats lethargy. Not to mention being fun...</p> <p>(And before you think I'll be bringing back the dreaded mullet: the next MacGyver will be a woman, according to <a href="https://twitter.com/thenextmacgyver">https://twitter.com/thenextmacgyver</a>)"</p>
Presenting a business case for quality documentation can sometimes be a difficult enough task. Adding to that the accessibility requirements, and the whole idea may resemble a mission impossible. The fact that official standards (WCAG and WAI-ARIA) themselves seem to require user manuals in order to be properly implemented, is not helping developers, technical communicators and content managers achieve the desired results. This talk will present the main points and a selection of tools to get through the labyrinth of WCAG techniques and guidelines, and help you make your techcomm project accessibility-ready. Welcome to A11y for Tech Docs!</p>
Do you feel like a fraud? Do you have that sneaking fear of being “found out” and exposed? Imposter syndrome is corrosive. It holds us back at work - especially in an industry where we can feel constantly under review by talented peers - and erodes our happiness. And the subject always comes up whenever technical writers gather; sometimes it feels like the very definition of a technical writer is “One who experiences imposter syndrome.”</p> <p>Why is this? The first, shorter part of this talk will cover some research and insights into why we, as documentarians, may be especially susceptible to imposter syndrome.</p> <p>But the field of tech writing is experiencing a swerve: a tipping point - a sea change in direction. There will always be a demand for ""old"" tech writing, but many of us will have to adapt to this new environment.</p> <p>In the second, forward-looking part of this talk, I’ll argue that being an “imposter” has its advantages during such a time of change. The very factors that contribute to our self-doubt are actually the qualities that will enable us to thrive as our role inexorably evolves to take on new, unsolved challenges in engineering information. The keys to our success: apophenia (the ability to see connections between seemingly random collections of information), empathy, and adaptability.</p> <p>Our future is bright if we pay attention to our new opportunities instead of that nagging voice in our heads.</p>
A picture says more than …how many lines of code?
<p>Firstly this talk offers an introduction to a variety of established as well as experimental visual documentation methods. Subsequently, it explores the question whether or not these approaches can be applied to software documentation in a reasonable way.</p> <p>In this regard it takes a closer look at individual methods and estimates their corresponding affordances in terms of time, skill, resources and potential automatization.</p> <p>Eventually, this talk presents an initial attempt to translate existing docs into visual languages and discusses the according outcomes.</p> <p>Primarily, the objective of reading and writing the docs serves the purpose to convey clear, unambiguous information, at the same time, the experience should be as engaging and pleasant as possible. Building a Visual Documentation Language serves to reach this goal.</p>
Most of the documentation we read today puts a lot of burden on us before we have the chance to get to the gist. Abstract and clear concepts are replaced by concrete and comprehensive ones. The real values are hindered by opaque clouds of facts about tools of trade. As a result, thinking and imagination are suppressed.</p> <p>But what if we can write documentation that encourages thinking?</p> <p>Let's look together on what really matters when documenting computer systems. We will discuss how a documentation and system design can walk hand in hand and to improve the communication between both humans and machines.</p>
