Andrew Spittle

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Matthew talked about how the concept of a minimum viable product would apply to documentation. The minimum viable product, MVP, is the belief that building software is expensive and risky. So sometimes the best solution is to build the bare bones version first and then rapidly iterate.

You want to test the feasibility of an idea before sinking more resources in to it. Even if you’re just spending your time there’s the opportunity cost of building software. By building as little as possible you can launch faster. Unfortunately this frequently means documentation is cut. This, in some cases, is because product managers don’t understand the value that documentation provides.

You can do early-stage testing with early adopters. However, if your audience is mass-market they may not be the best test audience. Matthew’s example here was, “How many software developers do you know that use Pinterest? What if they used tech-based early adopters as their test audience?”

The product you create must work better than existing solutions. This applies to the product, documentation, and the tools you use to create both. Sometimes printing out a form, filling it out, and faxing it back is easier than dealing with an Adobe browser plugin.

Unfortunately lots of people think of documentation as a safety net for your user experience. This isn’t necessarily a healthy relationship.

Interfaces are, at their base, about manipulating abstractions. Without a strong grasp on that iconography you’re going to have a difficult time using that product. This is a problem, though, that technical writers are well-placed to deal with. They’re frequently in a good place to help understand how users will interpret what you are saying.

One way to help with documenting your product is to pair with new developers as they come on board. You can document the difficult things as they have questions. This lets you save time in the long run as common stumbling blocks are removed and documented. Reference docs, in this sense, are a form of outboard memory. They’re primarily for people who understand how something works and are looking to refresh their memory. While reference docs are key for APIs and other elements they aren’t the best teaching tools.

To write the best teaching doc you need to, on a certain level, forget what it’s like to be an expert user of your tool. Personas can help with this as they help you come at a problem from a given perspective. The how-to document is, Matthew argues, the biggest impact for getting a user from zero to hero. It’s a tried and true documentation format but it works. How-to docs work with user experience design to effectively document the experience of using your product. If the process for doing something is complex to write then it’s likely too complex to use as well.

You can also use your how-to docs to regression test your user experience. When developing software you’re going to break something. Having how-to docs in place helps communicate how the software is supposed to work. You can catch bugs when there’s a deviation from that canonical how-to explanation.

There’s also a way for writers to be proactive in a lean development process. As Matthew put it, what if you thoroughly prototyped your user experience in words first? It’s an author’s equivalent of test-drive-development. Combining that approach with some UX design knowledge gives you the opportunity to truly be a leader.

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Geoffrey is the VP of Open Source Content at Pluralsight, a video tutorial company. He opened his talk speaking about Information Anxiety and how the book was written for someone to skim, flip, or read through. Each is a valid means for consuming information. Could we apply this approach to documentation?

Graphical elements allow your documentation to be consumed at different rates and in different flows. It can be more respective of your reader’s time. As part of this Geoffrey recommended reading Information Dashboard Design, which looks like a fascinating book.

One way that he’s used graphical explanations is through type. Yes, it’s text but there is plenty we can learn just from type. When the web started it was designed as a textual delivery system; graphical requirements weren’t necessarily considered. Many of our documentation systems still take this approach. A simple pull quote can be a graphical hook that lets someone skimming a document understand the core ideas. Combinations of font size and color also convey graphical meaning. Think of a stop sign or a warning sign as two main examples.

Icons are the next graphical explanation Geoffrey covered. One of his favorites is Symbolicons, an icon font that looks like a neat tool for easily adding vector icons to your text.

Beyond that the power of graphics is not just that we’re making pictures on the screen. The power lies in the explanation behind that graphic and its ability to communicate the meaning within a document.

I love this slide. Let's add it to the crowdsourced doc models. #writethedocs pic.twitter.com/tpWTGXq27f

— Heidi, Sticker Thoughtleader (@wiredferret) May 5, 2014

There are models for conceptualizing these explanations. Geoffrey walked us through examples of good/bad, good/better/best, before/after, and other core comparisons we understand as explanations. Many involve showing a reader the different types side by side. It helps understand how something can be transformed or what an ideal result is.

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Alex kicked of the set of talks after lunch. He got his start writing software and documentation for the django project. The people who come to django’s docs are of two groups: they’re looking for reference material for a project or are entirely new to django and looking to make a website. The latter group is who Alex focuses on.

In truth the django project has never written down the user profile for those new users. They assume that they know the basics of how the web works. django is a tool within the domain of building web applications; its docs focus on people looking to learn within that domain.

Alex is working on a cryptography program for web developers. He’s found similar tools have very poor documentation and sees the goal of his project as about education as well as development. If you don’t write docs for your world-changing idea you’ll lose.

Can you document around a usability problem? This comes up a lot around legacy software. The conventional answer is no. Alex argues, though, that we can write docs that illustrate how to use a product. What you can’t document around, though, is people’s assumptions. You need to shock them out of their assumed viewpoint. In this sense documentation and design are a partnership. Documentation partners with design to create usability.

If you pick an audience you can write your docs to those personas. It may not be useful for everyone but it will be useful for someone.

Additional reference material must be optional. If it’s necessary to comprehension it must be inline and part of the doc.

The most important thing Alex has tried to do with his project’s docs is to work toward fundamentally having no assumptions. They work to give users the full context of the project and not assume core knowledge.

Your docs should also be prescriptive. You’re the subject matter expert and should make recommendations that your users may not know to make for themselves. Nudge them toward good defaults. Your users may not need to know every single layer of possibility.

One of the most valuable things they’ve done on Alex’s project is to test the documentation with users. They give them the docs and ask that they try to solve a task. They’re not allowed to use Google or other resources, just the docs.

Often users don’t know what they don’t know. Nothing of consequence should depend upon something that your user doesn’t know they don’t know. This can also be where recommendations and nudges come in. It lets users understand what’s going on without necessarily needing to take the action themselves.

Part of asking for feedback on documents should be about giving those users the means of contributing that feedback. Let them help improve your project if they have ideas for doing so.

Something else to realize is that your users don’t care about your domain as much as you do. They may never say thank you, and that’s okay. To a user your domain of knowledge is the impediment to them getting their job done.

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Nina wrapped up the presentations before lunch. When she started college every Freshman had to take a writing course. The papers weren’t graded but her first paper did very well. As she sat down to write the next paper she thought, “This one will be even better.” She got to an empty page. Thankfully she got an extension; which got her thinking about how to make writing easier on herself.

When you’re under pressure the worst place to be is at the beginning. With nothing written you have no momentum.

Nina now works at a software company making development tools for mobile developers. Their customers create new projects that are already filled with template code that compiles and runs. They don’t start with a blank page. How can that programming approach be applied to writing?

The first thing we should absolutely be stealing is starting templates. Don’t start with a blank page. Make a ‘Hello World’ document. Make a template for every single type of document that you publish often. It’s not about the content; you’re just interested in setting the foundation for the layout, structure, and guide for published content you like.

To solve miscommunications around docs Nina recommends making a spec. For documentarians the doc is the product. The spec helps you get there. Use it to define the questions you’re answering for your readers and for yourself. What kinds of questions can we ask? Things that help us understand who the target audience is, the current state of the documentation on that topic, and who will be doing the work. This will change not just what you write but how you write.

A lot of us start with outlines when writing. It lays the foundation, or so we think. The problem is that the outline at the start of writing a doc is never the outline at the end of writing a doc. The programming lesson Nina recommends here is design patterns. This is essentially a prescription for solving particular patterns and problems in code. The solution is customized and implemented to solve the problem in a particular context. You can do this by starting with architecture rather than an outline. Know what type of document you’re writing and then start the process.

If you can't figure out what to call something, calling it twelve different things is the worst thing you can do @misskallisto #writethedocs

— Elizabeth Urello, eurello.bsky.social (@eurello) May 5, 2014

When writing docs we strive for clarity. But we often fail. On way this manifests is using multiple terms to refer to the same thing; consistency matters. A cornerstone of good programming is naming your variables. Nina argues that this is a cornerstone of good writing, too. Be consistent, be specific, and be deliberate in your naming and your writing.

Editing is another key component of good writing. At Nina’s job they do peer editing. To help clarify that concept Nina turned to the concept of code refactoring, or restructuring existing code without changing its external behavior. For your docs, don’t just edit, refactor.

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Mo spoke last year in a lightning talk and this year upgraded to a full 20 minute session. He’s a self-professed child of the 1980s and warned us of upcoming ’80s references in his talk.

Meeting notes are like the garbage trucks of the documentation world. They’re seen as boring and something that no one wants to spend their time writing them. Even during meetings people play iPhone games, read comics, and sketch emoji in their notebooks. Documenting what comes out of those types of meetings is a losing battle. When working at one particular company Mo became really good at sketching the poop emoji in his notebook. The act of “writing” in his notebook, though, meant he got pegged to write recap notes each week.

Mo had always viewed notes as regurgitation. The first thing he did was shift his perspective to one of curation. He asked himself, who’s my audience? Meeting notes might be for absentee people, people outside your business unit, or even people external to the company. You’re not writing meeting notes just for yourself.

Next you can create a shared need. What’s the most important thing people can get from those notes? Chronology isn’t as important as, well, importance. You can see this in sports articles. If there’s a buzzer-beating shot that’s what the articles lead with, even though it happened first.

Ditching chronology in meeting notes… I hadn't thought of it before, but it makes complete sense. #writethedocs

— Smiley Grumblesaurus 🦉 (@GrandmaHenri) May 5, 2014

Then, you need to WTF: Write The Facts. Heated discourse may take place but trying to recapitulate all of those opinions is not relevant. Focus on the facts of the meeting and stay diplomatic. Somethings are better left unsaid.

Make sure that when you include action items those items are clear. Define who is handling the task, what the task is, and when it must be delivered by. Vague goals in the meeting notes will just be forgotten.

How you deliver meeting notes also matters. Use a collaborative platform that lets you listen to the others at the meeting. You maybe inadvertently included some incorrect information, typos, or other inaccuracies. Avoid email as the final product of meeting notes.

Mo uses templates to make all this happens. It saves him time in putting together the notes after a meeting. Just make sure to change all the placeholder text before pressing “Publish.”

A great way to get people to read your notes is to include Easter eggs. It might be little things like, “Hey, if you finish your code review by the Wednesday afternoon deadline I’ll treat you to a free pint.” It helps prevent the tl;dr syndrome.

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Amalia works at MongoDB as a software developer. Traditionally in documentation we want to spread knowledge. Ignorance is the enemy. Ultimately, though, the struggle that comes in overcoming ignorance is one of the strongest feedback loops for quality documentation.

When Amalia was hiring TAs while working in college she learned that the best TAs were frequently those who got Bs and Cs in the course; the ones who struggled with the material themselves.

When she started at MongoDB Amalia was faced with learning how to work with a code base approaching 1.4 million lines of code. A lot of that works came in just reading the code and deciphering it. Some could be done by looking at user-facing documentation and learning how the product performed in an end result. At a certain point, though, all those strategies fall short. Reading the code can’t tell you the internal mechanics and design decisions that went in to building it.

https://twitter.com/foxesinsockses/status/463382706881966080

When reading the code falls short a lack of internal documentation hampers a company’s ability to scale. It causes growing pains across the board. It also impacts hiring as your new hires take longer to become productive within the company. Opening new offices and scaling horizontally also becomes difficult when you don’t have internal docs and best practices for self-learning.

https://twitter.com/Gamblest/status/463383717839241216

While you don’t want to push code that is inherently wrong you can start with rough code. Even if it’s wrong it gives someone a hook to come in and offer feedback. For Amalia this took the shape of a 1,300 word rant about working with a particular aspect of the code. She sent that rant to the two people most familiar with that part of the code. The response was really positive; there was actually a large audience of people frustrated with the same problems she ran in to. Other people said, “Wow, it’s great that someone wrote about this. It’d also be great if someone wrote about these other things.”

The trick is that you need to find your allies. Find those other people who are as confused as you are; there are always those people. Those same allies can help you spread the work out. It makes you not the single point of failure. It also lets you take the burden of writing off of the engineers developing the code. If you enjoy writing others will enjoy you taking it on.

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Heidi is a technical documentarian of about 20 years now. Her talk focused on bringing order to a chaotic environment. Her specialty is working with companies that have never had a technical documentarian before and helping them get a solid foundation in place.

I have a business card that says 'better & cheaper than having a developer do it' #writethedocs Heidi Waterhouse

— Elizabeth Urello, eurello.bsky.social (@eurello) May 5, 2014

Part of this involves trusting that you’re the starting point for these companies. If that company believed in documentation they already would have hired someone. Trust that you are the expert with the authority to bring that value and illustrate its impact.

The first thing you do is set up shop. Make a seating chart of the office so that you can remember where people sit and what their specialties are. Draw a map of the existing docs and how to get to them. It lets you know the neighborhood, competitors, and users. There’s always some conglomeration of poorly structured documents somewhere. Ensure you have access to them. Looking at competitor’s documentation gives you a sense of where your company stands. It lets you determine what environment your docs will be living within.

When writing documentation within a company, there’s no time for frills. You need to deliver early and deliver often. Or, you must talk about why you can’t deliver. You can get to precision between emergencies but you must ensure you’re dealing with emergencies first.

Draw your docs fast. No one can give you feedback if they can’t find and read your documentation. The early format matters far less than its delivered state.

The next thing you do is save the townspeople. If you can’t envision which person is being saved by that document then it’s likely not saving nor helping anyone. Address the biggest internal pain points and give them a structure to ask about things and give feedback. Those quick easy wins shows your value and quiets your internal feelings of being an imposter. In terms of giving feedback Heidi pushes all documentation changes through the same bug tracker and code process as the product. Documentation edits are created as bug tickets and assigned to her.

Then, you’ll want to check for scorpions. These are situations, not people. If you blame people you face an uphill climb; focusing on situations lets you solve things systematically. Look for hoarded documentation, carryovers from the last sheriff in town and then bring in the vigilantes. The vigilantes are those hoarding documentation; they care but are operating outside the bounds of the law. Rolling them in to the work you’re doing creates consistency without alienating previous doc owners.

The last thing you’ll do is build infrastructure. You should plat your documents and find gaps; consider the use, configuration, customization, reference, and necessary fixes for documentation. Your infrastructure for continued growth ensures that documentation is seen as a first-class citizen in the product and not a forgotten afterthought. Be the voice for docs at scrum meetings, architecture sessions, and more.

Documentation sheriffs are part of a town. You’re not a hired gun who rides in to town, shoots people, and leaves. True sheriffs build a community and long-term structure for the documentation they’re creating.

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Homer started the talks on Monday morning. His talk centered on flow and using permaculture principles to conduct documentation projects. Homer works as a technical writer, and has for about 25 years.

Permaculture is a word coined from combining permanent and agriculture. It’s primary use is in landscape and agricultural systems. While that’s where it began it’s spread since then. Bill Mollison was teaching permaculture in Australia during the late 1970s. It’s about work with nature, of protracted and thoughtful observation, and of allowing systems to demonstrate their own evolution. There’s a lot of space for allowing; there’s direction you do but not commanding.

Homer redid his backyard on these principles, ripping out a sterile grass environment and planting over 30 fruit trees. He’s now got a fully functioning ecological environment behind his house. The lesson is that diversity gives stability; ultimately the problem is the solution.

So, how does that relate to documentation principles? First, the model Homer works from in his docs is one of observation, design, and then evolution. Design may be where the bulk of the effort happens but everything starts with observation.

Observation, based on these principles, is without preconditioned ideas. You look at things with an open mind. As Homer said, if you feel like something is missing, spend more time observing. For documentation this means looking at things like flows of energy, existing corporate culture, the resources you need to complete the project, who’s available to help with it, the strategy to re-use resources throughout the company, and much more. Ultimately we want to discover the patterns of the organization, team, and readers. This is a phase we frequently short-change or skip all together in projects.

Design, then, is looking at zones of access. You make a small change early to create the largest effect. The edges of spaces are where the action happens; it’s where the energy is exchanged. In projects you want to design for collaboration and cooperation while yielding multiple things. Zones of access are where you can gain access to information. You can answer questions like, what does your reader need to know? What do they access most frequently? And, how can you help them? Cooperation does not mean competition; cooperation is about sharing information, chunking tasks in to specific buckets that can be distributed across a team. It’s something that’s frequently ignored in projects due to the urgency of direct action.

Evolution is knowing that your system will evolve and letting it. You continue to observe, refine your system, and keep a feedback loop in place. Growing your soil, or foundation of people, is crucial. This is the most valuable asset you have for continued evolution. For documentation you need to measure and evaluate while being open to new ideas. Training your team on new skills to fill needs helps, too.

A permaculture approach can be used to plan, design, and execute a documentation system or project that can be deployed across an organization.