Tag Archives: conference

Write the Docs: Scot Marvin – Wabi-Sabi Writing

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.

Scot covered how we can use wabi-sabi in our writing. He first started reading about wabi-sabi when his first child was born. He found the first rule of wabi-sabi seemed to be that you don’t talk about wabi-sabi. It has a respect for syntactic ambiguity which goes against much of our Western ideals. Essentially, though, it’s beauty in impermanence, imperfection, and incompleteness.

Our Hellenic ideals push us toward perfection, but ultimately we create very little of perfection. Wabi-sabi embraces the rustic and the simple. It allows for tranquility but also asymmetry. It’s not about being a Luddite. It’s also not complacency. Allowing for imperfection does not mean accepting the generic. You strive for excellence, not perfection.

Scot works in an agile software environment. Essentially agile means finding out where you are, taking small steps toward your goal, and then adjusting your understanding based on what learned. It, like wabi-sabi, is not about creating perfection. It’s a repeatable process that lets you improve and strive toward excellence.

He tries to abide by four suggestions in his writing.

  1. Less Faulkner, more Hemingway. They are the two extremes of America writing. Write in simple, clear sentences. Your documentation should be clear and concise.
  2. Less Coltrane, more Davis. Or, strive for tranquil writing. Miles Davis was known for his economical restraint when it comes to music. Scot strives to put support out of business with his restrained documentation.
  3. Less Versailles, more Ryōan-ji. Work toward simple writing. Your docs shouldn’t be the equivalent of the gardens at Versailles. This can also be thought of as the, “Don’t get too cute” principle.
  4. Done is beautiful. We can’t truly complete anything, but we can get it done. Incomplete, imperfect writing is okay. Incrementally make it better; don’t just wait for perfect completion.

Write the Docs: Lauren Rother – We Strongly Recommend You Write Best Practices

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.

Lauren is a tech writer at Puppet Labs. She focuses on the Forge, a repository of community modules for Puppet. At Puppet the docs team falls under engineering, and the writers are embedded within the various development teams.

The challenge they face is that users have different needs, environments, workflows, and most importantly, levels of experience. The experiment Puppet tried was the beginner’s guide to modules. They’re in the process of writing an advanced guide, which would incorporate what they learned from the beginner’s guide.

In the first draft they took inspiration from textbooks. They brain-dumped everything in to a Google Doc which they then sorted in to 4 sections. They wanted to present heaps of information so that everyone who needs a foundational knowledge of modules would be satisfied. It was immediately apparent that the document was overwhelming. It was hard to approach and the first section in the document was disproportionately huge.

What they realized was that the first thing they needed to do was create sign posts within each section along with sub-sections. The took a more orientation-based approach to writing the document. This second take at the document produced something much more readable and comprehensible. Large paragraphs were broken up and edits were geared toward orienting the user. It was still really difficult to navigate and locate distinct items, though. You constantly were going back and searching for where you left off; it wasn’t easy. In short, the doc at this point was really readable but not usable.

They realized they’d been working on a treatise, not a guidebook. They dropped the academic standpoint and textbook approach. What they really wanted was a doc that people would want to look at more than once, not something they’d only read because of its challenging nature.

In hindsight it seems really obvious that a step-by-step approach was necessary. It didn’t occur to them to take this approach, though, until they were 2 drafts in. The final version has a table of contents, headings, steps, introductory sentences and examples. All around it was a huge improvement.

Lauren couldn’t help from thinking about future improvements, though. There wasn’t enough get-your-hands-dirty details in the beginner’s guide. It was too high-level at times. She’s taking some of these lessons and applying them to the advanced guide to modules.

Write the Docs: Brian L. Troutwine – Instrumentation as Living Documentation: Teaching Humans About Complex Systems

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.

Brian kicked off the slate of talks after the morning break. He’s a software engineer who focuses on computer-to-computer programming. It’s not as much end-user software. He primarily works on real-time and distributed systems. A lot of this is for advertising companies and takes the form of real-time bidding on ads.

Advertising has become an engineering-driven industry. It’s lowered the cost of advertising and allowed people to spend as little as $10 a month for their business advertising. The nature of the problem in this world is it super low latency (less than 100ms per transaction) and global, highly concurrent nature. The complex systems to execute this have complex organizations around them. They’re tightly coupled to external systems and have non-linear feedback built-in to them.

Bad things happen when these complex systems fail. You’ve built them to solve wicked problems and when they fail they sometimes create even worse problems then they originally solved. Ultimately, “our ability to create large and complex systems fools us into believing that we’re also entitled to understand them.” To work toward that understanding we write documentation.

The issue is that complex systems are fiendishly difficult to communicate about. The gap of understanding is difficult to bridge in documentation. Any miscommunications around complex systems are accidents in the making. Documentation can help to reduce these accidents. It can help give everyone a greater shared understanding of the system. Without knowing how a system should behave you cannot really understand how it shouldn’t behave.

An issue with understanding through documentation is that the docs get out of date. Complex systems evolve and written words “rot” as the system moves on. Sometimes this falls on engineers for failing to update what they change. Or, engineers can be unaware of the system as it is actually used. This contributes to misunderstanding through docs.

Normal accidents happen as well. Every system has, intrinsic to itself, some failure. No matter how much we try we can never get rid of them, we can only choose how to react in the presence of such an accident.

How can we build better systems that distribute knowledge and better avoid accidents in real-time? Brian’s argument is for instrumentation. This reflects the reality of the system as it exists. Instrumentation allows the users and the engineers to explore the system as it actually exists. This exploration, done honestly, guides us to a new, better understanding of the system. Instrumentation also democratizes the organization around a complex system.

Troubleshooting complex systems can sometimes be limited by not having enough information. If you’re relying upon external services there’s a level of opaqueness that you cannot see through. But, instrumentation is not a panacea. It can also create an overload of information that floods your ability to make sense of the system. Too much information hampers interpretation.

On a darker note instrumentation can be used for undesirable purposes. Surveillance is a form of this. Complex organizations with excessive instrumentation can do evil things.

What we should do is write documentation with the instrumentation in mind. Procedure manuals and visualizations, for example, reduce the amount of complex knowledge required. The more contextual layers you add, the more you reduce the “big boards with blinky lights” issue. Instrumentation is like a suit. It needs to fit your mind. Cross-checks and documented error margins mitigate instrument deficiency. Checklists with references to instrumentation at decision points is key. It pinpoints where attention should flow and how to process it toward informed decisions.

So, instrumentation addresses the problems of documentation and documentation addresses the problems of instrumentation. Together they help guide and ensure the quality and understanding of complex systems.

Write the Docs: Christopher Kelleher – Make Music Not Noise

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.

Christopher wrapped up the first group of talks before the morning break. His first boss taught him that making sound is not the same as making sense. That concept evolved in his mind to, information is not the same as communication. The standards of music can guide us here.

Since that talk with his first boss Christopher has worked on dozens of types of docs. The metaphor or information and communication has helped him throughout.

The music world defines noise as sound without structure. When you take sound and place it within a satisfying structure you get music. The search for this satisfying structure is innate. When placed in an MRI and given unfamiliar music the intellectual centers of people’s brain light up. They immediately try to make sense of the sound and determine its patterns.

With documentation we tend to accept docs that are failures in the same way as unguided and unstructured noise. But we lack the same fundamental cognitive abilities to identify them. When a document doesn’t communicate it fails. Just like when sound doesn’t exist within a satisfying structure. The likelihood that a document without communication conveys knowledge is extremely low. Ask yourself whether the doc you’re creating contains the necessary information.

Next Christopher talked about deliberate noise. Many times noise is accidental, but sometimes it serves a purpose. The most common lie on the internet is, “I have read and agreed to the terms of service.” No meaningful attempt at communication resembles a terms of service. iTunes, for example, has a 29 page long terms of service.

It’s goal is not communication. It’s goal is to protect the legal interests of Apple and to force you to click “I agree” without reading. This is often what noise in documents does; it gets you to acquiesce.

Deliberate noise comes in to play frequently in the legal and government arenas. Documentation noise is treated as unavoidable. But we totally can avoid it! A musical document succeeds by feeding your brain what it craves; it satisfies the innate needs. This music-like satisfaction is more than a nice-to-have, it’s essential.

Write the Docs: James Pearson – Don’t Write Documentation

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.

James isn’t a writer by trade but is rather a system administrator. For him documentation is a way of ensuring that everything works and our users are happy. He works at iFixIt where they teach everyone to repair the products they use every day. The documentation on iFixIt’s site is all wiki-based and very graphics-heavy. About half the guides are user-contributed.

As James said, good documentation’s worst enemy is bad documentation. Not everyone loves writing documentation and when the love isn’t there the quality can suffer. There’s something different in our brains about docs. We don’t treat them like software and, as a culture, are sometimes numb to documentation. We assume it’s bad and avoid reading it. If we can focus on increasing the quality of docs we can combat this numbing effect.

When you allow bad documentation to linger it drags the quality of the overall library down. A similar effect to the broken windows theory. Bad documentations allows for people to internalize the notion that it’s okay to have crappy documentation. That’s not what we want; we want high standards for quality. As an aside, outdated docs fall in to this bucket as well. Updating them is frequently an easy thing to fix.

The first category that James really, really hates are auto-generated docs. There are three great virtues of a programmer: laziness, impatience, and hubris. Laziness is what drives us to create auto-generated docs. Frequently the result is not worthwhile, not in-depth, and not reviewed with an eye toward user-facing clarity. Javadoc may be a good tool but it’s gone bad. Just because you can do something with a tool doesn’t mean you should. Computers, at their core, suck at writing docs for humans to read.

James then covered the second category of bad docs, those that use overly verbose language. By knowing your audience you can find places to omit needless words. One audience may require great detail while another can do with just an overview. ssh allows for 4 levels of verbosity within the tool itself. What James seeks is a documentation equivalent of that.

The final thing James talked about was mistake-proofing. Humans will always make mistakes, but mistakes don’t always need to become defects in the final product. An engineer at Toyota came up with the concept of deliberately designing mistakes in to your product creation process. The trick is to fix these product failures rather than documenting around them.

After the talk James posted his slides. Check them out.

Write the Docs: Susan Salituro – From docs to engineering and back again

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.

Susan is a software engineer at Pixar and has also had a long career as a technical writer. She was inspired by last year’s conference and the talks that came out of it.

Her talk is about a story, a journey of career choices and being open to opportunity. She quoted Tom Freston who said, “A career path is rarely a path at all. A more interesting life is usually a more crooked, winding path of missteps, luck, and vigorous work.”

In college Susan wasn’t sure what she wanted to do. She love astronomy, though, and wanted to be an astrophysicist; the problem was that she didn’t truly believe she could finish a physics major. That dream was scratched. She had half the credits toward a math major, though, and pursued that. That switch left her with some free time which she devoted to English literature.

That combination led her to take a technical writing course. It opened up her eyes to the profession of technical writing. At the time she felt that was where she was destined to go. For a few years she followed that path. The community, conferences, passion, learning, flexibility all drew her to the industry. Susan enjoyed learning what customers did with a product. It was about the customer and making their lives easier. But, she started to wonder if there was something more, something deeper.

That led her to dig in to what she found interesting in technical writing and where her passion lay within that. Susan got really in to what made software tick. She’d spent so long understanding how programs worked from a user standpoint. Now she started learning more programming and digging in behind the scenes. She spent the next few years doing API technical writing.

Then, she made her way to Pixar. The manager there wanted to use DITA for a new project. Through that she got the chance to learn Python to write doc scripts and make to execute those scripts. While she never thought of herself as a programmer she had accumulated enough skill to enter that world and make programming her own.

The next challenge came in moving to the software release engineering team at Pixar. This pushed her to an even steeper learning curve where she was learning Perl and deeper levels of Python. The community she’d found in technical writing was still there, but it was mostly internal to Pixar. The mentoring and help came from inside the company but Susan didn’t get the sense of a large external community around these skills. The flexibility she found in tech writing also diminished. On-call hours were expected and work came at all times.

After moving to Canada, Susan changed companies and shifted to an information architecture role at a smaller company. She was now working solo without a strong internal community but was able to stretch her reach in to new roles that had thriving external communities. Unfortunately the company went bankrupt and Susan went back to Pixar as a Software Infrastructure Engineer.

On one level this new role meant reaching her goal of melding documentation and programming. They mandate was to find solutions for doc problems and address tools and process issues. The focus was not just documentation but the entire software life cycle. She worked on tools for the release engineering team, the quality assurance group, and more. At heart she still considered herself a technical writer.

Write the Docs: Drew Jaynes – Putting the (docs) Cart Before the (standards) Horse

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.

Drew opened the second day of talks Tuesday. He works as a web engineer at 10up and contributes to the WordPress project as well. His talk focused on WordPress’ approach to inline documentation.

Up until about 8 months ago WordPress paid very little attention to the details of inline docs. There were more than 10 years of loosely following phpDoc 1.0. The codex, a wiki-based documentation site, was still seen as the main entry point to learning more.

This wasn’t working anymore with hundreds of thousands lines of code. The codex had grown to 2,300+ pages of manually curated content. That means each release saw the docs team manually going through the codex and trying to create pre-release master lists of required updates in the docs.

Enter hook docs. The docs team decided to create their own doc spec, largely inspired by existing frameworks. They were expecting a large influx of contributors to docs and wanted to set a consistent baseline for new people to the project.

The evolution of the docs team saw them establish themselves as a more official contributor group. They did an informal summit at the Open Help Conference last summer, ran a codex survey to see how people used it, and developed a roadmap for documentation going forward. Never underestimate the power of a docs team armed with a roadmap.

As soon as that roadmap was in place the docs team was off to the races. The top item was to burn the codex with the fire of a thousand suns; but first they needed something to replace it. Work began on a parser and code reference theme and hook docs began in earnest.

At this point the docs team has 3-5 sub teams contributing to various aspects of the docs roadmap. There are weekly chats and virtual sprints over the weekends. Furthermore, the collaboration with other teams has raised the profile of docs within the project. 8 months in to this project they’ve documented every hook in the project, more than 2,200 of them. There was a 48% increase in inline documentation over just 3 releases spanning one year. Those same 3 releases saw 40 new contributors to docs.

The biggest difference is that there are now people paying attention to the details of documentation. It ensures things are consistent, complete, and reviewed. Developing that standard for documentation was immensely helpful. Part of that was taking the docs created over 10 years and developing that standard from the docs. In the long-term this allows them to adopt new aspects in to the spec without causing vast disruption each time.