The virtuous thank-you cycle

We talk a lot about vicious cycles, and how it’s easy to end up in bad places because the incentives are all bad, but let me tell you a story.

It’s a pleasant Saturday, my family is watching Star Trek: TNG together, and I’m in my home office, working on a side project and slightly resenting it. It’s the collateral for a workshop Carol Smith and I are giving at LISA about the non-technical part of interviewing, and we think it’s really an important part of helping people get jobs. So the workshop will be great and important, but I’m currently wishing I was doing something else. And then this comes across my twitter:

Marie says she uses the principles I espoused in that talk even when she starts side projects, like Call My Congress. Because she set it up to be easily localized, anyone could come through and easily add instructions in Spanish or Somali, without having to fight the project to do it.

I gave that talk 17 times. I took it to a different continent. I got most of my expenses paid, and I got an honorarium exactly once. I figure I spent 60 hours researching and writing it, and and 3-5 hours in prep and rewriting each time I gave it. I was working for myself, so no one paid me for that time.

A thank you note like this makes that all worthwhile. I give technical talks for the same reasons that novelists say they have to write – because it’s something burning in me, and I need and want to share everything I have learned the hard way so that other people don’t have to. In my grandiose moments, I think of it as reducing the entropy of the technical world, giving people a boost up the ladder. Most of the time I think it’s funny that all of my teacher-mother’s children have found our own ways to teach, far from school classrooms.

Now I have a job that pays me for development time for talks, and means that travel and conferences are not lost productivity for me, and that means the world to me, but most of the technical speakers you see at conferences are like I was — working evenings and weekends and taking vacation time to battle entropy with education.

I’m going to try to remember to do better about saying thank you, and thus spread the cycle of appreciation further and wider. A virtuous cycle perpetuates because the rewards are so good. Thank your mentors, and the friends who want you to expand your horizons, and the organizers who make safer spaces to speak in, and the bosses who don’t make you take vacation days. Thank them publicly and specifically.

New job title: Developer Advocate

I've had a lot of job titles in my career:

  • Technical Writing Intern
  • Queen of Documentation (It was 2000, OK?)
  • Technical Writer I, II, III
  • Technical Communicator
  • Senior Technical Writer
  • Technical Writing Consultant
  • Documentation Architect
  • Documentation Mercenary

You might notice a theme there. I've been a technical writer for a lot of different companies, because that's been my career, my expertise, and my passion. I want to take everything that's great about technology and make it easier to use, more transparent, more thoughtful, more humane.

Lately, I've been having trouble describing what I am doing in terms of writing alone. Two job interviews in a row, my interviewer stopped asking me questions about my qualifications so they could take notes on my ideas for their product. My conference talks are sort of nominally about writing, but actually about patterns I'm noticing in the world and in technology. I love writing, and I'm never going to give it up, but it's also…not quite a good fit anymore.

Through the power of All-Women-In-Tech-Are-Connected, I got an interview for a Developer Advocate position. I would never have applied for this position on my own – it's so far beyond what I think of as my skill set. But in the discussions and interviews, I really came to believe it was not just a company I could work for happily, and a product that I think is useful and not toxic, but a position that lets me get out there and do the kind of thinking and helping and problem-solving that I love.

Photo credit: Women of Color in Tech Chat

Developer Advocate is a super broad range of positions, actually, but our interpretation of it is basically me continuing to do all the things I'm doing now: conference speaking, blogging, listening, and noticing. It's just that now I'll be doing all that and getting paid for it, instead of using it as a loss leader for my consulting. I get to go out in the world, find out where developers and users need help, and figure out how to make it happen for them. We're seriously at "pinch me, I must be dreaming" levels of exciting here. I even get to keep writing a little, although I may have reached my personal career goal: not writing the release notes.

Yes, I'm being deliberately coy about my new employer. That deserves its own post. I'll just say that I think we're going to get along well, they say I get to continue to be a pink-haired weirdo, and I will feel proud of the product.

I honestly feel like changing my job title is like the day you get new shoes and you realize you'd outgrown the old ones without noticing.

Oh! This is so comfy.

Consulting retropsective

I’ve been doing Agile for too many years to feel like I’ve learned something unless I identify it with a proper retrospective. I’m about to start an FTE job, and my consulting will obviously drop way off (but not entirely). So here we go:

What went well

  • I passionately loved the independence. I could fire a client when I thought they were doing something that was stupid/unethical. I didn’t have to account to anyone for my time at conferences. I made it to all the weird middle-of-the-day school stuff. My spouse was in the hospital for 11 days, and I could absorb that without talking about it.
  • It really forced me to get better at negotiation, scoping, planning, and self-management. No one was going to save me by telling me the priorities of projects — that was on me.
  • I learned a lot about building a personal and professional reputation. It matters that I blog. It’s important to follow up on business cards and connections. I never advertised my services except by telling people they were available, and I had stages where I turned away work.
  • I discovered moxie as a selling point. Not unreasonable bragging, but people are happier when they spend a lot of money on someone who seems confident about themselves and what needs to happen. I would have guessed that would be a turn-off, but no, that mostly applies to earlier stages in a career.
  • I got to work on some kick-ass projects and refine what parts of writing and projects I’m good at.
  • I got to go to so many conferences and learn so much stuff about things that I never would have thought I cared about, but it all feeds into the hopper and then a week or a month or six months later, it turns out that data was valuable.

A smattering of the stickers I carry around with me

What needed improvement

  • Cashflow. Sweet fancy moses, cashflow. This year to date, I have pulled in about $30k and gone $10k into debt. I had two contracts die on me after I had turned down other work to take them, and a client that paid Net-45….ish. If I reminded them. As a sole earner for a family of four, including two teenagers, this is not super. If I knew I was going to make that persistently, I would adjust our style of living, but I kept optimistically thinking that the universe would not screw me over again, right? And this was just a little bump. It wasn’t.
  • Relatedly: taxes. I did not get that set up as soon as I should have and I will spend some time untangling it.
  • I needed some things in my contracts that weren’t there: a kill fee/clause. A late fee. I racked up about $700 in late/overdraft fees because I thought people were going to pay me when they said they were. This is not a malicious problem, it’s a problem because I had already exhausted my buffer cash.
  • I need to keep working on how I track time. There is a lot of my job that is basically talking to people, wandering around thinking, and staring at the ceiling. It’s legit work, but I feel weird charging people for ‘I mowed my lawn and also thought about your data structure problem for two hours’.
  • I need to figure out how to pay myself for loss-leader/reputation building stuff, like blogging and mentoring. If I classify it as “not-work”, it eats the leisure time I need to recharge, interact with my family, and sew nifty dresses. If I classify it as work, then it’s unpaid work, which has a lot of emotional stuff going on.
Empty wallet in male hands. Isolated on white. Studio shot.

Empty wallet

Action items

If I do consulting full-time again, here are some things that make it more likely to work out for me.

  • Start with 6 months of cash buffer instead of 3. This is because I don’t have any other income stream
  • Write my own contract (well, hire a lawyer to do it), and make sure my clauses about kill fees, late fees, and payment schedule get into whatever contract I sign.
  • Hire a tax accountant sooner rather than later.
  • Work on adding passive income to smooth out bumps.
  • Factor in equipment costs and less-obvious travel costs in my calculations (if you take 50 flights a year, you wear out luggage, even the nice stuff) (I’m using a 3-year old laptop, and software costs money.)
Purple spinner suitcase

My next suitcase – a slightly smaller TravelPro in PURPLE

BIG CONCEPTS small docs. User documentation is a failure of user interface. Faster and cheaper than making your developer write it. Elegant writing saves money. Paid by the anti-word.

Why are there no documentation bootcamps or schools?

Sarah Mei and Sarah Fox and some other people and I were talking on Twitter about code school graduates, and how they frequently do really well at mid-level positions because they have communication skills from their previous careers.

We all agree that teaching someone to write well enough to be a Professional Technical Writer is more than you could cover in a six-week intensive, probably. Depending on where they start. I could absolutely turn a motivated journalist into an entry-level tech writer in 6 weeks. They’re 3/4 of the way there already. But most people would need to learn the following from scratch (in no particular order):

  • Audience analysis
  • Task-based writing
  • Procedural writing
  • User story writing
  • Error writing
  • Bug writing
  • Conceptual writing
  • Diagrams, illustrations, and screen captures
  • Rudimentary tools use
  • Sentence construction
  • Bullet point use
  • Theory of simplified English
  • Accepting editorial feedback
  • Accepting technical feedback
  • Elements of information architecture and presentation
  • Elements of usability and accessibility
  • Style guide use

Even if you’re coming out of a liberal arts/literary background, half of that list is something you may never have heard of. You can construct a great sentence, and you know how to use a semicolon, but your experience to date has rewarded you for things that don’t matter at all in technical writing. You’ve gotten good grades for making persuasive arguments or writing pithy literature reviews, but no one in my English Lit classes ever told me that I was addressing the wrong audience or designing my headings badly.

So that’s a daunting list of things to try to cram to get people into what is, let’s face it, a less glamorous profession than Code Warrior. I happen to think it’s the best and most influential place to be in a development team, but that’s not what the pay scales say.

That said

That said, I think I could do a LOT with teaching code school students and other developers some really basic writing skills. I tried this out at a Workshop at Write the Docs this year, and it went pretty well. I’d love to present it elsewhere. I’m putting the outline below the cut, if you’re interested.

Give me your developers for a day, and I’ll teach them to write a well-constructed error code and a readable bug report and a coherent status email. Give me two days and I’ll teach them about audience and analytics and deletion.

I want to do this for code schools, so we can catch people when they are frantically learning, so they will remember to look it up later. I want to do this for open source projects, because it is so hard to find or hire a technical writer. I want to do this for conferences where junior developers are looking to elevate their game. I have been traveling around to developer conferences for several years now, trying to distill everything I know from 20 years of my career into something that has value for coders, and I am convinced it has value.

Continue reading

Open Source Citizenship Award

I was at Open Source Bridge this week, with my kiddo Baz. We were both giving talks, and I was giving a workshop on interviewing with Carol Smith. Also I got to MC the slideshow karaoke part of the after-party, which was huge fun.

But the big news is that I won an award for Open Source Citizenship. This was not captured in pictures, but I literally spun in a circle, trying to figure out who behind me was also named Heidi. They were pretty clear they meant me.

Open Source Citizenship Award

Shiny 3-D printed medal that says “Open Source Bridge Truly Outstanding Open Source Citizen 2017”

I have real trouble thinking of myself as an open source contributor – sure, I go to a bunch of open source conferences, and I write for, and I give talks about how to be a better self-documenting writer, and I livetweet almost everything I go to, but I don’t code, you know.

It’s like that moment when you recognize your internalize misogyny. Oh, I am devaluing my contributions for NO GOOD REASON. I have imposter syndrome not about my talent (goodness knows, I’m pretty cocky about that), but my place in the community. Any minute now they’ll find out that I haven’t edited Wikipedia in 9 years, and they’ll reject me! That’s not how it goes. Contributions of all types are valuable, and I’m glad to be recognized for what I do.

In 2009 or so, there was a giant fannish explosion we now colloquially call Racefail. One of the most valuable people/roles in the whole thing was “Archivist of the Revolution” – a position held by @ryda_wong and others. They read, collated, and commented on an incredible amount of data, packaging but not altering it so that we could consume relevant posts without seeking them out ourselves.

I don’t see myself as that dedicated to the cause, but it’s something I can aspire to — to offer up information, to curate what I see, to help create indexes and pointers. I do live-tweeting because I think it’s valuable and because it’s a way for me to manage my ADD. 8 hours a day of extremely thought-provoking talks is HARD.

For a little while, I thought that perhaps I was outshining other contributors because my conference persona is loud and tweety and charismatic. And I truly feel that charisma is not always the best indicator of value to a community. There are a lot of charming assholes in the world. I hope I’m not one of them, but I assume that charming assholes never notice it until someone calls them out on it.

But then I remembered that this is voted on by attendees. Individual people found what I was doing useful. And I remembered the very smart thing that my mom told me about compliments.

“Just say thank you. Arguing is insulting their judgement.”

So thank you! I’m going to be happy that I won something! It’s true: I do spend time, money, and energy on the open source community.

  • I mentor other writers
  • I spend hours and days crafting talks
  • I quietly support other women and under-represented people, dozens of hours a year
  • I contribute thousands of words to the corpus of knowledge with tweeting and blogging
  • I ask stupid questions so other people don’t have to

That’s a pretty good list. I’m happy with it. So thank you, members of the Open Source Bridge community. I appreciate your recognition, and I’m honored.

Lady Speaker Small Talk

Sometimes, I think the hardest part of going to conferences is the unstructured time – lunches and happy hours and sponsored parties. That’s the time I remember I’m surrounded by 2,445 total strangers. And I’m supposed to be networking with them. If I think too much about this, I end up at “what do I even do with my face?”

The goal is not really “networking” in whatever negative way you’re thinking of. The goal is finding interesting people and showing them that they have neat things going on.

It turns out that conferences are full of people who are alone or nearly alone. If you came as part of a team, or you are working the conference, the social stuff is different, but if you are alone, here are some things I do.

Look odd

I have fuschia hair that I wear in a variety of short, eye-catching ways. Since I’m almost six feet tall, I’m really easy to find in a crowd. You don’t have to make quite so striking a personal style statement, but it’s useful to have people able to find you because you’re wearing a tophat, or orange sneakers, or all safety orange, or whatever it is you decide on. Your conference friends, the people you have met at other conferences, will recognize it. Strangers will see you on stage and note the thing about you so they can find you to ask questions later. And if you make it something less permanent than hair color, you can not wear it and totally blend into the crowd.

Make a friend in the registration line

Odds are, you’ll be standing here a few minutes. This is a great time to turn to the person next to you and ask them their name, and what they’re here to see, and what they’re looking forward to going to. Not, like, all at once. Then you sound like a teacher asking about a book report, but as conversational starters. Is this your first year here? If you’ve been before, is there some local food I can’t miss? For the rest of the conference, you’ll probably be able to spot that one person you met early on and give them a friendly nod. And if you’re very lucky, the name on their badge will be readable.

Sidenote: The minute I get any standard-length lanyard, I tie a knot in the back of it so that it hangs higher on my body. Now people looking for my name don’t have to track their eyes past my cleavage. This is a habit I picked up several years ago, and I think that having your name as close as is comfortable and feasible to your face is a win.

Go to other people’s talks

It’s super tempting to hide in your hotel room frantically preparing for your talk. I’ve been there. But I also know that a large part of the value exchange in this conference is that it consts money to attend and I’m not paying anything. So I try to go to a talk in as many slots as possible. I might take the slot before my talk off, and sometimes, depending on how drained I am, the slot after. But mostly I really want to go to people’s talks. It may seem odd, since I don’t have power over any servers, I code in no languages, and I only nominally work in teams, but I still get a lot of value out of conference talks. The technical ones help me keep a finger on the technology zeitgeist. The people-oriented ones always teach me something, because being a consultant is both managing up and sideways.

I always livetweet the talks I go to, but that’s for a different post. Mostly what I want out of going to other people’s talks is an understanding of a technology or application of technology, and to have attended the same conference as other people. At a multi-track conference, it’s easy to go to different conferences in the same venue, depending on your interests, but if you go to talks, you’ll always be able to ask what other people went to, what they thought, and then respond with what you learned or wanted to argue about from the talk you watched. “What talk did you get the most out of today” is a lovely, neutral question and sparks a lot of conversation.

Remember the theory of paradoxical popularity, or charismatic loneliness

I’m sure there is an actual psychological term for this, but lazy googling did not find it. Did you know that the prettiest girl in a high school gets asked on fewer dates than an average-looking girl? Did you know a lot of people that you think of as important, or influential, or famous, eat conference dinners alone? 

That may be by choice — there’s a lot of people energy involved in giving a talk and then doing the networking afterwards, so if a person wants to eat alone, let them. But I’ve noticed that people I think of as amazing sparkling wonderful stars in this context are eating alone. I think we are all valuing their time as too precious for us, and not even asking, a kind of low-level excessive politeness. I’m not saying you should ask more than once, but it’s probably ok to say, “Hey, I really admire what you’re doing, I’d like to talk about it more, do you have someone sitting with you at lunch?”

Talk to the sponsors

These people are sitting at the vendor booths, handing out swag and trying to get a badge scan off you beacuse someone is juding them on this back home. If you do want something on their table, walk up, make eye contact, and ask for it, don’t just grab. If they’re busy talking to someone, spend a minute or two listening to the pitch. You may not be a person in the market to buy things now, but it never hurts to treat the people who make conferences happen well.

The same goes for organizers. They seldom get to see the conference, because they’re making it happen. The have worked months on this, and whether they’re paid or unpaid, they are on constant alert for Something Going Wrong. It’s really stressful! So if your organizer stops and asks you how it’s going, or if you have what you need, remember to say thank you before you start in with a complaint.


I got this one from Eric Holscher at Write the Docs. We tend to naturally form a circle when we’re standing around talking about a topic.  It takes a special kind of courage to approach a ring of backs. Instead, as you’re standing in the ring, open up space between you and a neighbor to leave room for a new person to slip in and add to the conversation. You’ll be surprised by how much difference this little bit of body language makes in making your informal conversations more interesting and varied.


The best way to love a conference is to be part of it. Not every conference offers this opportunity, but if you can volunteer, you should consider it. Having a set role makes it easy to interact with people. “Here’s your badge and your t-shirt. Have a great conference!”. You’ll also get to know other volunteers and organizers, as there’s almost always a backstage that attendees don’t see. This is where I have had some pretty amazing conversations over the years.


I have a gallon bag of stickers that I carry from conference to conference. People take some, I collect some from tables and people and vendors. The stickers come with stories and then I can re-tell the stories at the next conference. Much like doing a jigsaw puzzle, sorting through a pile of stickers encourages people to stand around and have an idle conversation without feeling tense or anxious. I’m sure if everyone did it, it wouldn’t be novel, but even if you have one type of sticker, from your employer or personal brand, it’s still something to talk about and enjoy together.

On the topic of business cards

Spend money on business cards. I know it seems like an antiquity in the age of tap-contact-swaps, but there’s something about the tactile delight of a good business card that makes people comment on them and remember you. Mine are especially bright, with a plasticky finish. The back of the cards more-or-less matches the color of my hair, which serves as a good mnemonic. I get mine from Moo, which means I can have the fronts different designs — I’ve used this to put 5 or 6 witty tech writer slogans on the front, and I happen to know that people will pin them to cube walls because they’re funny, bright decoration. There is no higher state of winning than having your business hard pinned to a cube wall. In contrast, printing yourself or using a cheap printing service means you’re handing out something that feels disposable, so people do dispose of it.

If you have to hand out your company cards, that’s what you’ve got, but consider if there’s some other personal branding that would feel natural and satisfying to you. At my last conference, I gave away tiny (1/4 inch) hedgehog stickers for people to put on their badges as an indicator that they’d met me. Spontaneous fan club! Or something.

Done talking now

One of the hardest things I had to learn was how to end a conversation gracefully. I almost always start by thanking someone for their time/insight/advice. Then I say something like:

  • I’m off to the next talk! Catch you later.
  • I need to make a call.
  • I’m meeting someone in a few.
  • I’ve gotta go do a thing.

I know – a thing? But it works. 

    In summary

    If you think of conference conversations as purely utilitarian, they will be difficult and dry. Instead, think of them as a way to learn a new and interesting thing from everyone. Good luck out there!

    New Workshop at Portland Write the Docs

    I’m excited to announce that I’m  going to be presenting a workshop associated with Write the Docs in Portland! Write the Docs is an exciting community-based conference that draws in a mixture of technical writers, support folks, independents of all stripes, API writers, open-source developers, and a wide variety of other types of people. We all come together to talk about how we can use documentation to get our point across to users, and how our experiences can help others. It’s the technical conference of my heart.


    This year’s lineup looks amazing, as always, and I am assured that the snack time will once again have house-made graham crackers, so I am excited to be attending. (Seriously, the catering is delicious)

    I’m teaching a workshop on structuring and writing documentation. It says in the overview:

    This workshop is designed to teach you a few basic theories of technical documentation, such as task-based topics, reusable content, and writing for an audience. After the overview, you’ll learn techniques for writing bug reports, error messages, and onboarding instructions in a tool-agnostic, repeatable way. You’ll leave this workshop with a handful of techniques, templates, and tests that will improve your team’s communication and your life as a developer.

    What that means is that I’m going to give a crash course in the key theories of modern documentation and then guide people through some exercises that will hopefully help cement the theories. My goal is that people will leave with some tools that will help them think through their options for documentation. I know that many small companies and organizations don’t have enough money or enough work to supprt a writer, but there is still some degree of writing  that needs to be done.

    If you’re interested in attending this workshop, you can buy tickets through the Write the Docs site. If you’re interested in this workshop or a full-day workshop for your team, you can contact me. I have a special workshop I’m designing to walk a team through their onboarding procedure so they can get it out of their heads and into shareable form. Documentating and streamlining onboard is a really cost-effective way to save time for senior people.

    Publish and pull managers

    @kwugirl has done some great work around ask culture and guess culture (, and how frustrating it can be when you are framing communication the wrong way so that you are constantly rubbing on someone. 

    Ask culture says that it’s ok for someone to make a direct request for a favor, and it’s equally ok to tell them no. Guess culture is more face-saving. A request in guess culture would look like a hint or ignorable indirection when translated to ask culture. Corporate America tends to default to ask culture because of… a lot of reasons.

    But ask and guess culture are about making requests of someone who has power to grant them. How do we want to talk about this when we are dealing with our managers? They want things from us, we may or may not have the ability to grant them, but the power differential is all different. 

     I think of this in terms of internet architecture – publish vs. pull. 

    Some people work best for managers who provide regular feedback and consistent updates on what’s going on in the manager/employee relationship, the project, the company as a whole. The publish manager will tell you regularly how you’re doing without needing any prompting.

    Some people work better for pull managers. When they have a question, they can ask and get an instant answer on how things are, but on the whole, the relationship is much less focused on status updates either direction, and much more on blocking disruption. The manager exists to protect the time and autonomy of the employee, and the employee doesn’t get much direction unless they ask for it.

    Of course, neither of the methods is bad or good, they just are. The problem is when you have a mismatch between the method a manager uses and what the employee uses or is comfortable with. 

    For example, if you’re a pull person, all that feedback and mentoring and goal-setting and communication feels like noise or even micromanaging. Getting status updates all the time feels like an expectation that you should be doing more. And on the flip side, your non-communication feels to a publish manager like you’re not doing anything, or worst-case, that you are deliberately concealing problems. Why won’t you disclose, why do they have to pry your status reports out every week?

    If you’re a publish person, and your manager only talks to you when you ask a direct question, and they put off status meetings if there’s nothing really important to talk about, you get kind of paranoid. What terrible things are they hiding? Are they angry with you? You sent in a report and you didn’t get any feedback on it, was it bad? What’s going on up there? A pull manager with a publish report will appreciate that they know what’s going on, but they consistently forget that their taciturn default causes actual anxiety in this person. Everything’s fine until you say otherwise, so what is this about?

    Ok, so it’s yet another binary to divide the world into, like the introvert/extrovert oversimplification. What does it mean for your actual life?

    Now that I’ve realized this, it’s changed the way I interview. Of course, we don’t always get to pick our managers, but at the moment when you do, ask the questions. 

    • “Do you prefer to update people on a schedule or when they ask?”
    • “How does your most successful report communicate with you?”
    • “What’s your favorite kind of update meeting?”

    You don’t want it to be too leading, because when someone is interviewing you to be their report, they really want it to work out, at least if they are the kind of person you want to work for. When they are in the room with you, they are thinking how to work you into their team, their workflow. They’re trying you on, including your communication style. And it’s their job to work with you, so they might unconsciously bend to meet your preference if you make it too obvious.

    If you’re a manager, the same thing applies. A candidate might be perfect in every other way, but if it seems like you’re going to have to ask them every week for their updated status report, or if they are going to want a ton of feedback from you and you’re a more hands-off person, you may want to add that to your decision matrix and decide if that’s an amount of effort you’re willing to expend on negotiating your natural communication style.

    We can all work with people who have different communication styles. We do it all the time without thinking about it. The best plan is to do it mindfully and patiently, realizing that most people are not actually trying to make you irritated or confused with their style, and that your style may be hard for some people.

    Many hands make a messy wiki

    In October, I attended HydraConnect. To my relief, it was not a networking event for evil comic book characters, but rather an in-depth conference for people running the Hydra software, which is used in higher education (and other library-like places) to organize digital collections.

    When I walked in the first day, I didn’t even know that much. I’d been contracted to attend the unconference days and add a technical writing perspective to a distributed open source project. I wasn’t sure if I would actually add value, but it seemed worth the experiment, and I learned and taught a bunch of things, which I will summarize here.

    Your documentation needs a lifespan

    There are two problems in software documentation:

    • Getting anyone to do it.
    • Getting rid of it.

    This is especially true in distributed open-source projects because there are many people contributing, but seldom a firm hand disposing. My proposal is that you PROGRAMATICALLY make your wiki pages expire after a year to trim down your documentation cruft and help keep all your docs accurate.

    Scenario: You sit down and check your dashboard. Three notices appear for pages expiring this week. You click on the link to the first one. It is a workaround for a bug that has been patched. Do nothing. This data should die. The second one is a valuable tutorial that you know people still use. You check to make sure it still looks accurate, and click the Renew button. Safe for another year. The third link leads to a requirements page that should get updated now that some of the software mentioned is too old to be supported. You edit the page to be accurate and click Renew.

    I came up with this idea because of some work I’d done years ago with people interested in sunsetting personally identifiable data. This is not quite the same as Right to Be Forgotten, it’s more that just because we can store an effectively infinite amount of data doesn’t mean we should.

    Do you think there are actually 36 million people working for the government? No, but anyone who has worked for the goverment in the age of data had their information collected and NEVER PURGED. A huge part of that vulnerability is because our data never expires.

    Data should have a lifespan. Technical data should get reviewed every year. Credit data should roll off after seven years. Your entire childhood posting history should get wiped when you turn 18. If we were more mindful about this, we’d have cleaner docs AND fewer horrifying data breaches.

    Your documentation should get treated like code

    This is not a new concept, but it’s especially useful for distributed teams.

    • Keep your docs in a repository
    • Write bugs against them
    • Include them as part of features
    • Write tests against your docs. If a novice user can’t follow your directions to do a task, you are not done. You can also use your docs as a test. If you follow the directions and the thing doesn’t install, you need to find out where the problem is.

    Good examples are as important as good explanation

    I could spend 300 words explaining to you how I like my peanut butter and jelly sandwiches made (toast, raspberry jam), or I could hand you my sandwich and let you see for yourself how it works.

    Many people need that concrete example to understand what is possible for them to accomplish. Some of my current favorite documentation are the Swagger API docs. They are not very wordy at all, super minimal, but you get a sample site that works, and then you can play with it, and the documentation is all baked into that. I can see how it’s supposed to work, instead of following a process and hoping I get it right enough to work.

    Search is how new users learn

    When you get stuck on a new problem, especially if you’re not sitting next to someone who can answer your question, what do you do? Most developers and IT people I’ve talked to Google it, almost as a spinal reflex. If you are not doing internal analytics and designing internal SEO around that, then Stack Overflow is doing a better job supporting your product than you are. That’s not catastrophic, but it’s not great, either.

    Set up analytics on your wiki, your web page, your help, wherever you are storing your documents, and start watching the search terms people are using. If your documents don’t answer the questions, write more. If the queries are using the wrong language, add better tags and keywords to your documents so they’re findable. I’m really glad someone wrote that, but it is a tiny bit worse than useless if no one ever finds it.

    Drawing the elephant is better than explaining one piece at a time

    Do you know the story about the six blind men trying to explain an elephant? One gets hold of the ear, and says, “I percieve that an elephant is very like a fan.” Another finds the elephant’s flank and deems it wall-like. Each person has a different experience of the elephant and even talking to each other, they can’t conceptualize “elephant”. Is your documentation like those people talking to each other? Has anyone provided a picture or description of the elephant? High-level conceptual topics are both difficult to write and technically complicated. You have to understand both the audience and the product. But without that description, you just have a bunch of disparate tasks.

    Which leads me to my next point…

    Context increases compliance

    Knowing why I’m doing something makes me much better about doing it. I don’t let strangers poke me with needles, but I do get my flu shot, because I have enough context to know that it is the lesser evil.

    If you’re asking people, especially volunteers, to do work, you need to be able to explain how their effort is going to be a benefit to the organization. It doesn’t need to be An Epic Explanation, just a little something to guide people. “Let’s get these chairs stacked out of the way for the karate class coming in.” is much more contextual that “We need these chairs in stacks of four.” Be sure you are providing acessible context for the product and the project.


    Distributed teams that are not specialist writers can still create documentation, but they need to get rid of old docs and they need to have a clear vision of what they are doing and why.


    I really enjoyed the experience of the conference. Badges with pronouns! Other women, of all ages. But I also enjoyed being a technical writer at people. I’d like to do that again, for other projects that can’t afford a writer but do need a writer perspective

    (crossposted and updated from LinkedIn, thanks to Sumana for the nudge)

    Contract additions

    Last year, I signed 4 contracts for work-for-hire. I estimate that will be average-to-low going forward, but I don’t have enough data points.

    Every time I work with a company, I come up with something I want to remember to specify for the next time, or at least attempt to negotiate for.


    Work-for-hire does not entitle anyone to my other intellectual property.

    Pay me. On time.

    Give me the tools to do my job.

    Intellectual property grabs

    Someone, somewhere, has built a really terrible work-for-hire contract that specifies that anything I create while I’m working for a client is the intellectual property of the client. That’s just laziness. Or at least, I hope it’s laziness, because otherwise it’s greed. If I didn’t watch out for that clause, I would sign away authorship of my tweets, my blog, my fanfiction, my work for other clients. Strictly interpreted, if I signed that contract and wrote the Great American Novel, $large-employer would own the rights to it. To any patents I obtained. To any of the fruits of my mind.

    I’m not ok with that.

    Almost always, I point out that the clause is over-broad, and what on earth are they thinking, and the hiring manager apologetically crosses it out and we carry on. But it makes me cranky every time.

    I’m doing work for hire, which is a really specific category of labor that means I retain zero rights to the things I produce for pay. I can’t even use them as writing samples unless I get written permission. Played out in another industry, it means that the woman who provided all the phonemes for Siri’s voice a dozen years ago does not get paid by Apple. She did work for hire, the company that owned that resource sold it to Apple, she gets nothing. Which is hard luck for her, but is the way work for hire is. Most of the time, the things I write are wrong or obsolete in a handful of years anyway. The company is welcome to keep them.

    Payment terms

    I pay $15 a month or so to manage my invoicing for me. I enter in all my hours, they send email to my clients, and my clients click ONE BUTTON to transfer money from their account to the ACH system, which means I get a direct deposit. In the last year, this has worked correctly about half the time.

    One employer insisted on cutting paper checks, 30 days after I invoiced them, and mailing the checks, which I then had to deposit. That did NOT make me feel favorably about working with them. Also they fired their accounts payable person and didn’t tell us. Ugh. This whole system made me feel like they were going out of their way to extract maximum interest from money I had earned.

    One employer was surprised that I did not like the idea of billing monthly and then getting paid 30 days later. I know I should have a cushion and all, but YOU imagine not getting (probably) paid for two months after you start work. On a three month contract. Also, they were not clear that the ACH system only works on bank days, and does take some time, so if you start the payment on the 15th, I will not get the money until the 21st, and I will be cross.

    Two employers were a delight, paid promptly and painlessly, and I have nothing to complain about.

    My takeaway is that I am adding a late-fee clause to my next contract. If you don’t get me the money on the day we agreed, much like my car loan people, my rent people, my credit card people, and every other business on earth, I will charge you a late fee. I’m currently considering how much would be enough to motivate good behavior without seeming ridiculous, but late payments have cost me at least $500 in the last year.

    Also, I always at least make a bid to get time-and-a-half if I go over 40 hours. I have to do crunch, but it’s worth at least asking if they’re going to pay me for my midnight oil. This rarely works, but perhaps it moves the Overton Window?

    Hardware and access

    When you’re an employee of the tech people type, you expect to get a computer when you walk in the door. That is your work computer, you use it to do work things, it connects to the corporate email and the Confluence and the VPN, it has an image that is supported by IT (assuming there is an IT). When you leave, you give it back to the employer, slightly deprecated, perhaps covered in stickers, and hopefully without any unfortunately embarrassing files.

    When you are a contractor, it’s all a bit muddier. Half the jobs have provided me a computer to do my work with. Half of them want me to bring my own device. The problem with bringing my own device is that I may be far outside of the norm for what they expect. If my employer does not purchase it for me, I do not have a MacBook of any description. They’re fine pieces of machinery, but they do not run most technical authoring programs, and the thousand-dollar markup is a bit steep for me.

    This was a real problem when I was contracting with a Mac shop. They would send me instructions on installing the software using homebrew, and I’d have to say, “I can’t test that, I don’t have a machine for it, could you please just set up an AWS instance for testing for me?”. Over and over, they’d forget that I was just not running the same OS as they were.

    It’s a problem when the VPN the client is using and that I must access hasn’t been updated since 2012 and doesn’t support Windows 10 (what I’m on), Windows 8.1, 8.0, or 7. NOW how am I supposed to see the product?

    Everytime I hit one of these roadblocks, I spend time that I could be spending on writing the documentation wrestling with the toolstack. I guess if you want to pay my consultant rate for me to watch youtube videos about hand-editing my registry, I’ll do it, but I’m pretty sure that it doesn’t take many hours of that to make it cheaper to just send me a computer set to employee specifications, or build me a dedicated hosted test instance. If only we had a globally-accessible cloud of computers which could be securely accessed and used to run software, eh?

    When I finished in 3 or 6 months, I could send the computer back. You’d have access to all the source files AND the software that I used to write them, I wouldn’t have mucked up my personal computer with your weirdo firewall hacks, and everyone would be happier.

    You know that tweet about how you have to get approval to spend $500, but you can call a two-hour meeting and no one blinks? That is so visible in contracting.

    So I’m going to see if I can add a hardware provision into my next contract. I can’t write about your software if I can’t use it, and I can’t use it easily if I don’t have the same toolstack that your developers do. And I’m AWFULLY expensive as a mediocre IT administrator.

    What about you? Do you have anything you write into your contracts?

    I’m still debating about how I feel about insisting on a site visit. It usually makes my contracts go better, but it’s also awkward to arrange reimbursement if I’m not in the sytem, etc.