Month: April 2013

April 9, 2013

Write the Docs: Tim Daly – Literate Programming in the Large

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.

Tim’s talk required some previous knowledge of Donald Knuth. If you don’t know who that is Wikipedia has a good summary. Tim’s background is largely with the Axiom algebra system.

Tim talked about how back in the 1970s you programmed in very small files. Nothing could be more than 4K so you ended up with these trees of tiny bits of code and relied upon build systems to put it all together.

IBM’s standard for documentation requires things to be written at the 8th grade level. This is understandably quite tough when you’re documenting complex algorithms.

Tim knows what code he wrote years ago does. He knows that if he takes it out things will break. The problem is he doesn’t know why he wrote it in the first place. This was tough when he faced the task of working with 1.2 million lines of uncommented code. The 8th-grade level documentation didn’t really help. In the early projects he worked on they didn’t write down the “Why” of code. Turns out that’s really, really important.

Tim sought a technology that would let him capture the “Why” of code. This, essentially, is literate programming and stems from Donald Knuth, the writer of LaTeX, METAFONT, and many more pieces of code. A literate program should pass the Hawaii Test. This is where you take the program, print it in book form, give it to a programmer for a couple weeks, send that person to Hawaii. When they’re back they should be able to work on and modify the original code as well as the original programmer. If you have that, you have a literate program.

The book form of a literate program includes all the necessary source code to build a system along with all the documentation and narration required to understand that system.

Tim argued that programming teams need an Editor in Chief. No one should be able to check in code without this EIC affirming that the code has an explanation along with it. The EIC gets between developers and the repository and says, “We’re writing a book about this code. You can’t check in code without the code and the story about what the code does matching.” When you have the explanation along with code you can compare a programmer’s stated goal with the reality of what the code does.

Companies depend upon pieces of software that former employees created. If you don’t understand that code you end up rewriting it. By ensuring our programs are literate programs we provide for stronger future proof code.

April 9, 2013

Write the Docs: James Tauber – Versioned Literate Programming for Tutorials

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 started things off after the break talking about a combination of ideas around literate programming and version control. He pitched it as a socratic talk that would pose more questions than answers.

James comes from a background of more than 20 years involvement in Open Source projects. He’s the CEO and founder of Eldarion which builds websites in Python and Django.

In June 2003 James posted to the Python mailing list about how feature structures could be implemented in Python. He worked up an example that somewhat like narrative programming. A method in which you explain to humans what the code is doing while you are writing the code.

Much of the talk went over my head so these notes aren’t the greatest. The gist seems to be that literate programming is not a means of redoing how we do documentation but, rather, a way we rethink programming. Writing the code and describing the code ought to be part of the same process.

April 9, 2013

Write the Docs: Daniya Kamran – Translating Science into Poetry

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.

Daniya started by stating that she is not strictly a documentarian. She’s a translator and interventionist. She turns crazy black hole-style concepts in to simplistic solutions. She focuses on questions like, “How do we turn around how people view nutrition?”

Documentation is an intervention. You’re creating an intervention from the perspective of the user. It changes the way they relate to a product and their train of thought when using the product.

The techniques and processes she presented are not a checklist. They’re strategies you can employ selectively to reach your goal. Her goal is to give you a poetic lens for your work. If you don’t like poetry, scientific documents, or want her to just show you how to write the docs then you’re not going to like this.

Poetry is very good at immortality. When you write you cannot write thinking that what you’re writing is never going to be seen again. If we assume documents are temporary it will come across in our writing. The user can tell. Poets write to transcend time. As programmers and as documentarians we don’t do this. Even if no one understands your work they should at least know that you wrote it. Write thinking that you’re a bad ass. Here’s Daniya’s guideline: Good writing will get replaced. Bad writing will get replaced immediately. Epic writing will be edited. Be epic.

Poetry is always about a dilemma. There’s something about to happen that you can’t quite figure out and need to solve. We assume that people know why they are reading the docs. There needs to be a context for what is being created. Docs, ultimately, answer the question, “What do I do?” In many, many docs this is not obvious. Your worst enemy is not a competing document; but a lack of initiative. Someone is going to read what you wrote and nothing will happen. In making dissonance obvious we create a sense of urgency, increase user autonomy, and provide a call to action.

Daniya says we should be biased. There is such a thing as a point of view. Scientists are very allergic to a point of view; they don’t like it at all. We associate objectivity with intelligence, even though that’s not always the case. The person reading your docs is coming to you because you’re the expert. They don’t want to do the thinking that you did. They want the answer. There’s a reason opinions flow and have an impact. A lot of it just has to do with assuming you are the expert and writing accordingly. Influence your readers. The goal is to be holistic. Encase your opinion in objective analyses as well as other opinions. Having the point of view provides the reader context. They can understand that you’re human.

Another thing scientists are allergic to is error. Poetry deals with it in a fascinating way. In some ways poetry is all about error; bad things happen all the time. As Daniya said, “Why is epic poetry still epic when everything is going wrong?” Poetry deals with things as part of a cyclical process. When you view things as part of a process it removes a large aspect of the negativity. Daniya also phrased it as, “a lack of error is very contrary to human ability.” An error is not a consequence, it is amendment to the process and a part of the process. It’s temporary and provisional and will, eventually, be edited and improved.

Poetry is very, very good at reiteration. What reiteration allows is for us to remember the purpose after every major turning point and complexity. People should not forget why they are reading what they are reading. Reiteration allows them to connect the current complexity back to the original purpose. Periodically bringing back context allows a reader to never lose sight of what you’re trying to do.

Metaphors are, in some ways, the most important point. All the evidence you’ll be drawing from to write your docs already exists. We merely rearrange bits of information in new and interesting ways. All we are doing is creating metaphors. They allow us to rearrange the patterns of our mind. We’re making remote associations between things we didn’t think were related at all. The reader fills in these patterns and associations and, thus, connects more deeply to your writing. Instead of pushing something out of the page the reader is pulling it out of themselves.

As documentarians we are adding to how people view communication. The way you ensure that your documentation is eternal is to make sure as many people as possible can read it, leverage it, and connect with it. The bottom line in all this is elegance. Can you make your documents elegant? If you can capture this in your words and in to your page then you have done everything you can.

April 9, 2013

Write the Docs: Noirin Plunkett – Text Lacks Empathy

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.

Noirin opened the second day at Write the Docs by stating that we are basically hairless monkeys. We’re inherently emotional people.

Ein + fühlung: The German root of empathy. Our ability to communicate, and to do so with empathy, is what helps us create these social connections. Facial expressions, body language, and more help us cue these reactions and connections.

Text, though, can remove emotion from our communication. We lack the facial expressions and more subtle indicators that help us in person. We have a tendency to fill emotional voids with negative emotions. This is particularly true in high stress situations.

The rapidity with which we can compose digital text is not ideal if we’re trying to solve complex problems. What works for in-person conversation does not work as well in a text format.

A lot of the time we don’t write. In email or in documents we aren’t invested in we, essentially, speak with our fingers. For people we have a connection with, that’s fine. When writing documentation we don’t have that same relationship with our audience. We don’t know their background, we don’t know why they came to the document, and we don’t always remember that communication is more than just transmission.

Learning social rules is an ongoing process. It’s exhausting and difficult for many. Noirin refers to it as running in emulation. It’s like booting up a virtual machine to try and understand how something works in a difference context.

Oblique Strategies from Brian Eno was mentioned. It’s a way to help with creative problem solving. So when you’re stuck on a problem you can draw a card and apply that to the situation you’re facing. They’re not so much advice as a means to remind you how to think about problems.

Noirin discussed a few strategies for making our docs more emotionally engaging. First, we have to understand expectations. This applies to many aspects of our communication. The expectations our users have when reading documentation, when a boss reads our email, and more are important to how our text is received.

Most people assume their incoming communication has tact attached to it. We don’t assume communication is rude and abrasive. When it is, it surprises us. To solve this Noirin recommends we all attach a little tact to our output.

The next strategy Noirin covered is to argue that zero is not negative. If we can try to recognize when we’re projecting negative emotions in to a space that has no emotion we’re assuming. If it’s unclear what the emotional context is, ask. That’s the only way you can be clear about the intent of a message.

If you transmitted a message and a different message is received the onus is on you. You have to make sure your audience understands what they’re reading. Communication is a two way medium and if something is misunderstood it’s not entirely the reader’s fault. The reader is the only thing that matters with documentation. When in doubt we should rephrase something. If you have to ask whether a sentence is grammatically correct, it doesn’t matter. Rewrite it.

The readers of your documentation don’t know how you feel. Our readers can’t see us, they can’t hear us, they don’t know if we’re having a good day or a bad day. Stating our emotions is a good way to get conversations back on track. If a conversation over text isn’t going well, state your emotions.

Noirin recommends moving through communication flow like this: email, IM or IRC, voice, video, real life. Those are in increasing order of fidelity. If email doesn’t work, move to IM. If that doesn’t work, move to voice. As she put it, “the fastest way to pass a Turing test is to pick up the phone.”

Perception is reality. If someone feels attacked, for example, they will shut down. That inherently makes their feeling reality. Reality is not what you’re trying to communicate, it’s what they’re feeling.

Noirin’s last point is that if it doesn’t matter, do it their way. Don’t be a stubborn fool just because you want it done your way.

April 8, 2013

Write the Docs: Teresa Talbot – Technically Communicating Internationally

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.

Teresa continued afternoon sessions by talking about the why and how of working abroad. She’s been a technical writer for about 20 years and spent 7 of those years working outside of the United States.

There’s a strong demand for technical writers outside of the US. This is largely because English is the most-spoken second language in the world. Lots of tech companies abroad wanted English-speaking technical communicators. Teresa has even worked for companies in the UK because they sought a US-specific technical translator.

The first route to working abroad is to have a company sponsor. This is what allowed Teresa to work and live in Holland. While this gives you certain benefits like state-run healthcare and whatnot it also more directly submits you to the more unique aspects of that country’s tax and employment laws.

Another route is to work as a contracting American for an international company. Teresa did this for a translation company working in Japan. Since Teresa was billing from a US social security number she didn’t need a work permit which made things more convenient.

You can also start a company abroad. Teresa did this in Bulgaria and while she had a business license she never did get a residency permit.

Overall Teresa’s talk dove in to lots of the nitty gritty in working abroad. Not the best content for notes but I noted what I could. 🙂

April 8, 2013

Status

Not quite 4pm and I’ve written 3,500 words at Write the Docs. Fun day so far and a solid conference.

April 8, 2013

Write the Docs: Nisha George & Elaine Tsai – Translating Customer Interactions to 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.

Nisha and Elaine work at Twilio where a large portion of documentation is owned by the support team.

Why do people write to support? They’ll ask questions like “Can I do…”, “How do I…” as well as report things that are broken. A customer company thinks of documentation as something that is helpful to your customers as well as helpful to the company. From the company perspective docs provide a consistent answer that’s inline with what the company wants to convey. Documentation is, essentially, a way to maintain a healthy relationship with customers and maintain expectations.

Support can own docs that compliment engineering docs. You don’t need to spend a lot of time gathering topics for docs. Every ticket that comes in to support is an opportunity to document the answer to that. Documentation, then, can decrease the increase in growth your support team sees in tickets.

A primary goal for your documentation should be making answers easy to find. Having questions be phrased as the customers ask them is just one way to do this. The overall structure of a knowledge base is also important. It has to be logical. Creating those buckets for common questions and tasks with your application can help guide a user from one piece to the next. Finally, your docs have to be searchable. Not having that is a deal-breaker.

Your customer support team takes care of new features, products, and bugs while the documentation takes care of known issues, features, products, and workflows.

How will you know that you’ve created a successful documentation structure? First, customers will become doers. They’ll trust that they can become self-sufficient with your documentation.

April 8, 2013

Write the Docs: Kevin Hale – Getting Developers and Engineers to Write the Docs

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.

Kevin was the next talk in the afternoon. Also, check out my notes from UserConf for notes from his talk there. He talked about Wufoo.

The ease of use Wufoo has means that, well, just about anyone can use it. Every person on their original team of 10 people wrote documentation. The secret, as Kevin puts it, was that everyone was working in customer support to some extent. They sent about 800 support emails a week to a user base of about 500,000.

Wufoo sought to create software that people had a relationship with. They were fanatical about creating meaningful relationships. They approached new users as if they were dating them and existing users as if they were married to them.

When it comes to new users, first impressions matter. The homepage, landing pages, plans/pricing, login, and support are the typical first impressions. Kevin prefers to focus on things like the first email, the login link, the first support interaction, and other specific pieces of the customer experience.

One way this looks in practice is how Chocolat allows you to keep using all the features after the trial period. Only thing is they force you to code in Comic Sans. Little touches like that matter.

Kevin also mentioned the site Little Big Details which collects lots of these kind of touches. WordPress is even in there. 🙂

Kevin mapped common marriage issues (money, kids, sex, time, others) to product issues (cost, users’ clients, performance, roadmap, others). As he put it, “divorce is like churn in a marriage.”

Kevin and the founders of Wufoo sought to create a support-driven development process. The way you make this work is simple. You just make everyone do customer support. The creators become the supporters and, thus, can’t ignore the things that cause users grief. This helped Wufoo scale their customer growth without causing an exponential hit on their support volume.

They learned a few lessons from this:

  • Support-responsible developers give the best customer support.
  • Contextual documentation is key. For example, clicking the “Help” tab takes you to the portion of docs for that feature.
  • Engineers who do support run experiments. Wufoo did this by having an emotional state drop down to their contact form.
  • Support-responsible developers actually create better software.
  • Support-responsible developers respect the people who do support full-time, every day. Their first full-time support person was revered because everyone understand what that job was like.

They spent 30% of their time in internal tools. As Kevin put it, some of the best software they created was stuff that no user interacted with. It’s wroth taking care of the stuff your employees work with every single day.

The prevent their user relationship from atrophying Wufoo included a “Since you’ve been gone” view in their application. Each time a user logged in they’d see a timeline of what features had recently been added. To be included in this list they required developers to have finished the documentation. So if a developer wanted their feature in front of every user, they wrote docs.

Kevin also posted his slides over on Speakerdeck.

April 8, 2013

Write the Docs: Leah Cutter – Generating a Culture of Doc

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.

Leah kicked off the afternoon sessions by talking about how you can encourage engineers to do the “write” thing. She focused on discussing the ideal. Not everything she covered will work but it’s a starting point.

Leah is a technical writer who is a Knowledge Management Specialist at Salesforce. She’s been working as a technical writer since 1985. As she phrased it, it is her job to generate a framework for engineer-generated content. She tells engineers what it is they have to write, where they have to put it, and what it should look like.

This engineer-generated content includes code comments, README files, specs, team sites, wikis, email announcements, and much, much more. You’ll notice external, customer-facing documentation is not on that list. That’s intentional.

By primarily focusing on internal processes you can create a culture of doc in your company and among the engineers.

Writers are outnumbered by engineers. Even at a documentation-strong company like Salesforce writers are just a small fraction of the workforce. By getting them involved you increase your ability to document things.

Within a company your knowledge exists in the minds of subject matter experts. These are frequently engineers. To be successful you need to get it out of people’s brains and in to text. When the knowledge doesn’t live in someone’s head it means someone wrote it down but you may not know where it lives. This causes the next problem, organization.

Salesforce, in part, solves this by having an entire team dedicated to internal documentation. They handle the internal architecture, processes and knowledge sharing across the company. It’s a 7-10 person strong team. A lot of this is code documentation as Salesforce is a monolithic piece of code. Some of the other docs are around building out data centers, servers, and more.

Even if your company won’t ever create an internal documentation team there are things you can do. Leah gave some ideas for how you can start generating useful processes and tools. The first step is finding the people around your company who are like-minded people. Seek out those people who care about documentation and give them a forum in which to participate.

Leah’s found that engineers break down between three roughly equal groups. Those who are eager to help, those who are willing to help but need guidance, and those who are curmudgeons.

One thing Salesforce does to motivate engineers to write documentation is hold internal documentation hack days. They kick it off with a talk, set clear guidelines throughout the day, and set a fun theme (e.g. “Doc like a pirate day!”).

The number one thing with creating a culture of documentation is to understand that some text is greater than no text. You have to start somewhere and anything you can create is progress. You can fix the text later; the first step is to get it written down.

The curmudgeons in your company will argue that good code documents itself. As Leah put it, good code only tells what something does, not the intent behind it.

April 8, 2013

Write the Docs: Virtual book sprint

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.

Bart talked about virtual book sprint. This stemmed from the X windows system which is one of the oldest window systems out there but has a very small developer base. About two years ago Bart decided to address this problem. He based it on Google Summer of Code sprints. Unfortunately getting people together in a distributed project with a small contributor pool is difficult.

They used Gobby to write docs up in Markdown. About 2 people put together 40 pages of developer documentation.

They learned a few lessons in this project:

  • Have enough people: People must be committed for the entire time. “Local pairs” would be a thing to try.
  • Have tools solidly in place and tested.
  • Nothing will happen after the sprint. Nothing.

Editing and writing are only part of the work. The tools and processes are also vitally important to the project’s success.