- No description.
- Number of videos:
The command line can be your best friend! Git is an amazing tool that helps developers collaborate, review and manage code, but these same tool also work for writing and managing documentation.
Learn how we use tools like Git, Middleman and Markdown in building and managing the ArcGIS for Developers website (https://developers.arcgis.com). I'll share some Git basics and give some insight into how we do things like create, collaborate and version our documentation all the way up to how the final website is built and deployed.
"Write the Docs" is so often a line item found at the end of a project plan. But documentation deserves so much more attention and thought as good documentation does more than just describe how to use or implement a new feature, particularly in the case of API documentation. It is both the shop window and instruction manual. The tone of the documentation represents your product, and the complexity, simplicity or ‘magic' needs to shine through.
My talk will focus on two objectives:
1) Why does Documentation deserve product planning on its own?
2) What do you mean Documentation as a Product?
We can all agree the world is under-documented. However, some of the documentation that currently exists, shouldn't, and it trains users to ignore the other docs we've spent so much time crafting.
We'll talk about common documentation traps, including autogenerated text and poka-yoke replacements, and how to recognize and purge them in your own projects to create a better user experience.
Human intuition about complex systems is pretty abysmal: we have neither the scope of imagination or the experiences necessary to predict the varied behaviors of our creations. Humans operating these systems--in stable and disaster situations--must rely on a combination of faulty intuition, information coming out of the system and static documentation created by the designers of the system to guide them in their actions. In this talk I will focus on the interaction of instrumentation and static documentation on human operators. In particular, I will contend that by insisting on rich instrumentation system designers will gain a deeper intuition of their work, generating better static documentation and more contextual information for use by operators. I will further contend that this environment is conducive to smooth functioning of the system and creates a culture of constant improvement among the operators and the engineers.
I will use historical examples and my professional experience to argue this position.
Can the values of music guide us to create better documentation? We’ll look at examples of noisy documentation and consider how we can use the noise vs. music distinction to improve the world by documenting it better.
sound without structure = noise sound + satisfying structure = music information + satisfying structure = successful documentation
First we’ll examine cases of intentional noise – documents that are designed to be hard to follow. Think convoluted cable bills or droning usage agreements. This is noise with a purpose: if we give up on following along, the document has done its job because the original goal was to make us surrender, not understand. We’ll talk about how to isolate the noise and demand higher standards.
And then there are documents that mean well but perform badly — the audience can discern a melody, but it’s either buried or gratingly inconsistent. Examples include tediously detailed consent forms, haphazard project documents, or reports that drift through random facts and jargon. This is the dissonance of badly structured information — making sound without making sense. Applying a musicality standard can guide authors out of the muck.
You've probably seen (and maybe even written) API documentation so reference-complete, it puts the OED to shame. Useful API docs cover every endpoint, parameter and variable--but not all API methods deserve equal prominence.
This talk is about creating better API documentation through empathy. We'll talk about delighting readers by knowing your audience, showing them where to begin, and explaining why your API matters in the first place.
When people think of documentation standards, I'd wager the first thing that comes to mind is probably something like "uniformity", or "best practice", or "one voice". And in consideration of that, most people probably also view standards as the de facto "starting place" for all the things to come after.
So what happens when you turn that idea on its head, that is to say, 'write the documentation first, and develop standards later'?
In the WordPress open source project, we did that. We developed an inline documentation standard using 10 years of contributions as a starting place.
This talk will cover some of the challenges we overcame to develop a new standard using legacy documentation. Also:
- Tools we used to assess our existing documentation "style".
- How our new standards have been applied in practice.
- How having a standard has allowed the docs team to rise to equal footing.
It is rarely that a documentarian is brought in at the beginning of a company or project. More commonly, we are called in sometime just before or sometimes slightly after a project is released. We need to hit the ground running, maximize our value, and deliver something before the product is rejected for being undocumented.
Join me for a discussion of my techniques and stress-tested questions for how to get minimum viable documentation out of a motley collection of gists, outdated specs, and time-crunched developers. See some immediately-applicable techniques for getting good-enough documentation out the door.
My specialty as a technical writer is establishing a minimum viable documentation set, establishing tools and procedures, and training in a less battle-hardened writer to take over.
I'm a non-developer working with a community including a bunch of mostly-volunteer developers, and for years our developer documentation wiki was quiet and mostly static. I didn't touch it, since I don't know enough to work on developer resources, right? Wait, no! I realized that even if I can't update it all myself, I can help the developers with it, including a bit of persuading them.
I'll explain some of my strategies for making working on documentation more appealing and rewarding for developers, including by lending it some aspects of the quick feedback that people get when writing code.
This includes things like: Ways to make the wiki feel active and alive, since nobody likes to hang out in a ghost town. Good questions to ask that encourage people to write things down. How to make first edits easy with bite-sized tasks and prominent "todos" that entice people to click that edit button. Finding people who prefer to ask permission first before making changes, and being there to give them permission! And the best "trick": advice for effective ways to thank people a lot, publicly and specifically.
The “Getting Started” page of your product is the most important page for bringing new people onto your product. In the best case, it introduces readers to your product and convinces them to use it. Too often, though, it becomes the “Getting Stopped” experience, with readers getting repeatedly frustrated. Poor documentation, from the Getting Started page on, causes many developers to leave your content and product behind. Outdated information, rude warnings, bad metrics, and poor content strategy all contribute to the “Getting Stopped” experience.
This talk examines several practical solutions that tech writers can use to engage readers and create a better first impression. Drawing on examples from Google’s Cloud developer documentation, I focus on how users can define solid metrics for success and encourage reader participation. With these simple but robust solutions, you too can bring more people to your product, getting them started and keeping them around.
Agile development environments bring increased versions, more due dates, and the accompanying headaches that go with publishing more frequently. And yet, writers must still maintain an emphasis on helping readers with the best documentation we can produce. So, how do we focus on producing documentation that is perfect, permanent, and complete?
The Japanese concept of wabi-sabi refers to an appreciation of the beauty in the imperfect, impermanent, and incomplete. These are qualities of Agile documentation. And they're beautiful. No, really. They are. This talk will detail my journey to let go (meh, for the most part) of the need for technical communication perfection. I will also offer tips for my fellow control freaks.
Writing best practices documentation is definitely an art, but that doesn't mean a little science can't help us along. Through some trial and error, I've uncovered some tenets of writing engaging, readable best practices docs. I'll walk through a bit of my path to discovery as I highlight and give examples of successful and (enthusiastic) reader-approved best practices documents.
The Mozilla Developer Network is an open-source documentation wiki for web developers, which is written by really passionate, smart, and inspiring people. Most are not paid employees of Mozilla. All of them are helping make the web a better place by writing, editing, and reviewing articles. How do you support a diverse community, acknowledge many different voices and perspectives, be open and inclusive, and still get things done (especially when you can't force anyone to do anything)? In this session, I’ll share what I’ve learned (and keep learning) by working with, in, and for volunteer communities; including how to be more transparent, create opportunity, and broadly share ownership.
In this presentation, I explore the role of documentation and technical writing in shaping larger recordkeeping and memory practices. How does documentation shape institutional memory? How does it validate and enforce definitions and boundaries? What roles do documentarians play in the larger ecosystem of development?
Drawing on my experiences as a UX Researcher and an academic HCI background, I introduce concepts from archival and critical theory. Examining both data and metadata structures, I argue for an infrastructural understanding of documentation, one that acknowledges documentation practice as crucial scaffolding for the development process. In conclusion, I present recommendations for maximizing the value of archival documentation and improving data retention and retrieval.
The urge to document is at the root of many bad presentation habits.
Despite a renaissance in the art of presentation - think TED Talks, Nancy Duarte, Prezi, and Ignite – we still experience more bad presentations than any lifetime deserves. Even with compelling content and conquered nerves, a presenter’s visual materials can totally tank a talk. And documentation is often to blame.
The real culprit is a conflation of documentation and presentation. Many slide collections end up being an awkward mash-up of the two, and documents suffer when we force them into the mental model of a presentation. (NASA and the military offer striking examples of these failures.) Why have the differences between documentation and presentation been lost? How can we make better sense of these two forms to create more engaging presentations and better documents?
If elegant technical help pages are the shiny, sleek roadsters of the documentation world, the plebeian meeting minutes are the dump trucks. Despite being regarded as an unglamorous business tool, minutes serve an important function for communicating effectively with colleagues.
Meeting minutes document changes to business operations, chronicle the decisions that were made, capture the essential gist of discussions, and serve as handy references for those colleagues who were unable to attend the meeting--or for those who indulged in siestas during the gathering. Minutes can even justify whether a meeting was necessary in the first place.
Effective minutes can save companies labor costs: well-written meeting notes can prevent both meeting organizers and absent team members valuable time that would otherwise be spent trying to bring absentees up to speed. Accurate meeting notes can clearly define policies and expectations in a workgroup.
In this presentation, we will discuss best practices for documenting and curating meeting notes. Using meeting templates, de-mystifying technical jargons, breaking free of the chronological reporting, adhering to the WTF (Write The Facts) approach, carving time for editing notes, charting follow-up tasks, and judiciously spicing up otherwise-mundane topics are examples of these best practices. Special emphasis will be placed on writing with clarity and empathy in mind for team members, whether they were present at the meeting or not.
Information is powerful — every day we see it transform the world around us.
Documentation doesn't always have to be about a software workflow or open source project — it can be used to develop and convey ideas much larger than yourself. Information architecture is a powerful tool for developing ideas over time. It enables us to evolve and distill information at a much larger scale than a single person or team could ever achieve on their own.
Take these concepts, and apply open source workflow tools like GitHub's Pull Requests and Write the Docs, and the distributed evolution of ideas and information has never been more accessible.
We'll explore these concepts, learn how to foster a community of distributed contributors, encourage contributions early on, and more.
Python-Guide.org will be used as an example, a Python-specific knowledge base written by 168 people and accessed by over 50,000 people every month.
Most of my career as a software engineer, I've written documentation for very general purpose tools, where users' had an existing familiarity. For the last six months I've been working on a cryptography library, a domain most developers are ignorant of. We set out with the goal of making our documentation accessible to any developer, regardless of previous cryptographic experience, which presents unique challenges. This talk will dive into what these challenges are, and how we try to solve them.
Permaculture is all the rage in the organic and urban farming circles, but it is a design science rooted in observation that has applications far beyond vegetables and fruits. Its basic tenets include observing the environment to discern the patterns, the risk areas, and other factors that will influence your work, and then working within those constraints using the least amount of energy and costly outside inputs to produce a harmonious, sustainable, and perennial system that yields a healthy return and requires the least amount of work to maintain.
This presentation introduces some of the core practices of permaculture that can be immediately applied to any project to make it more successful, more enjoyable, and better suited to its intended audience.
Participants will discover:
- Why it is important to design from the patterns to the details.
- The edge where two systems meet (think engineering and customer service) yields the most innovation.
- Diversity is important to incorporate and honor.
- Ways to stack function… where one element performs multiple roles (like single-sourcing).
- How to plan for zones of access… so that your audience can quickly locate the most important, most frequently used information.
It's a fresh and intuitive approach, a Zen view of something that many of us have done for years. In Permaculture, the problem is the solution. Or perhaps more properly said: in any problem lies the solution.
As Frederick Brooks observed in "The Mythical Man-Month", computer programmers build not with boards and hammers but with "pure thought stuff". Sometimes it can be difficult to explain abstract technical concepts just with words. Fortunately we can use colors, shapes and animations to explain ideas that would otherwise be confusing. You'll see dozens of examples and learn to make your own.
A good doc is like a good program: beautifully architected, free of clutter, and easy for others to understand and maintain. In this session we’ll explore a programmatic approach to writing conceptual content, including the application of design patterns to writing, principles of good doc structure (architecture), and the importance of word choice and clarity (naming your variables).
We’ll review “code samples” - examples of real sentences from docs - and refactor them into clear, straightforward explanations that help the reader learn. Throughout the talk, we’ll introduce a new way for developers to think about writing and for writers to think about the technology we are documenting.
When your company’s codebase is large, complicated, and mostly undocumented, there is a huge burden to bring new hires up to speed — not to mention facilitate communication between distributed teams. How can you leverage the knowledge of experienced engineers — and the ignorance of new engineers — to guide your efforts and create a valuable resource?
At MongoDB, we now have the Hitchhiker’s Guide to the Codebase, an internal documentation resource covering everything from an introduction to our build tool to detailed explanations of internal server mechanisms. Content is contributed by engineers across the company, based on their frustrations and requests from other engineers, and edited by volunteers. The most valuable content is often written by engineers who had to struggle through learning about those topics on their own.
I’ll talk about how I started this initiative without any knowledge or power, how I recruited volunteers, and the impact this has had on productivity at our company.
You're working at a startup building a "minimum viable product" -- and everything about the product is being cut down to bare minimum to reduce the risk and cost of failure. Deciding what to include in "Minimum Viable" is difficult, and the value of documentation in service of product development is often misunderstood by project managers who work in this style, who often choose to forego documentation altogether.
I will make the case for including documentation in "viable": We'll consider ways of understanding your target audience, helping introduce them to your software and getting them unstuck, and make the case for minimum-viable in-house developer documentation.
(00:00) Marcia Riefer Johnston - @MarciaRJohnston - Write Tight(er)—Revisited
(0:05:28) Dirk Myers @DirkMyers Test Those Docs!
(0:10:49) Eric takes a picture
(0:11:04) Anne Gentle @AnneGentle Open Source Docs the Hard Way
(0:17:22) Dan Stevens Write, Measure, Repeat
(0:21:14) Chuck Toporek @ChuckDude EPUB in a Nutshell
"We don't do translation; we only post to our website in English." Think again. Over 80% of Internet users have English as a second language or as "no language." Whatever you share online is destined to be translated into other languages with Google Translate and other free tools.
You don't have to buy an expensive set of localization/translation tools to get started. You don't even have to create translation memory. You simply have to think and write differently. And, most of what your high school English teacher taught you won't be of any help. This brief presentation will cover the key stumbling blocks that Maxwell Hoffmann discovered during his 12 years in the translation industry. In this session you will get a taste of how to "write tight", eliminate stair-step lists, minimize unnecessary tables and the trouble with gerunds, among other things. The good news? This method of content creation is also more effective for client retention with your clientele who are native English speakers.
Twitter Engineering has grown quickly, to well over a thousand engineers in the space of a few years. In the process, scores of teams have developed hundreds of individual services and libraries. During this time, these teams have been supported by at most three fulltime tech writers.
This is a story of how we work towards creating the culture of documentation. To implement this culture, we needed to introduce new tools that are seamless for the developer workflow and to bring the teams along with education and training. In this talk, you will learn what worked and what didn’t for Twitter engineering documentation.
Twitter is a large organization with many projects, a variety of languages, and wildly varying standards for documentation. This talk shares the experiences of our newly formed university engineering education division.
- Building and distributing documentation tools for a large in-house technical audience
- Evangelizing for broader developer participation in documentation
- Using rewards, policies, metrics, and public shame to drive documentation quality
It is rarely that a documentarian is brought in at the beginning of a company or project. More commonly, we are called in sometime just before or sometimes slightly after a project is released. We need to hit the ground running, maximize our value, and deliver something before the product is rejected for being undocumented. Join me for a discussion of my techniques and stress-tested questions for how to get minimum viable documentation out of a motley collection of gists, outdated specs, and time-crunched developers. See some immediately-applicable techniques for getting good-enough documentation out the door. My specialty as a technical writer is establishing a minimum viable documentation set, establishing tools and procedures, and training in a less battle-hardened writer to take over.
We'll take a tour through API documentation land, comparing the features and usability of different API doc sets. Interoperability is important, and making an easy-to-use API available can be a significant component of a company's success. Based on my own research, plus consultation with software engineers, product managers, and other technical writers, I will discuss what makes excellent API documentation. Here are some samples of great API documentation features that I have found.