The Seven Righteous Fights: Overview

This is a series derived from my popular talk “The Seven Righteous Fights”. It’s not an exact transcript, but I think having a written form to refer people to greatly increases accessibility and gives me room to expand my thoughts in a way that is not compatible with speaking.

There are seven fights that I have over and over again, whenever I start at a company. The more software you build, the more it’s obvious that there are seven fights that it will alway pay to have.

My background as a writer means that I am trained to perform a lot of analysis and synthesis. If I don’t understand the product from value proposition through implementation, it means that I am not the writer I want to be. I call it being a full-stack writer. The problem with having all this training in analysis is that you can’t exactly turn it off. I don’t stay in my lane well, I can’t notice problem that only fall into the narrow category of “documentation”. They’re all documentation problems, they’re all software problems, they’re all design and usability problems.

I’ve worked for roughly 15 companies and my conclusion is that when we create something new, we tend to make similar mistakes every time. This is probably because we all tend to settle in a comfortable stage of product development. Some people prefer mature products, some people like the very beginning and hate the mature product maintenance. But that preference means we don’t understand pain points that happen at other stages.

I’m an early-stage person. I love writing the first version of documentation. I love that green field and that new product smell. But I have done enough mid-stage stuff to know the emergent consequences of early-stage decisions. And like everything you’ve ever read about compound interest, early mistakes compound until they are enormous.

I was working with a startup that was pushing super hard to get their product ready to demo at a big industry conference. They were stripping off every feature they didn’t absolutely need in order to make sure they made their deadline, and I was helping. We made the deadline, there was documentation, and they got a POC contract… with a company in Brazil.

In the process of rushing to get ready, we had stripped out all of the plans to make the interface labels link to a file we could localize, and we had hand-coded all the labels. Now instead of handing off a single file to be translated into Portuguese (and having standard labels that could have been done with Google Translate, in a pinch), we either had to branch and hand-code Portuguese labels or spend twice as long digging into the original code and fixing what we had hacked. I’d love to tell you we decided to do it right, but you all know too much about software to believe that happened, don’t you?

The compounded interest from not using a best practice of referred labels when we built the user interface cost us five days of developer time to fix the wrong way, and two weeks to fix and rebuild the right way. That’s a relatively common example of things people skip and pay for later.

Leaving important considerations “until we get a working prototype” means that it’s going to be harder and more expensive to retrofit. Having these fights early prevents you from doing the software equivalent of poking chocolate chips into already-baked cookies.


Next: The Seven Righteous Fights: Localization

If you’d prefer to watch the talk as I delivered it:
Shortest recorded version: At The Lead Developer 2016

Longest recorded version: At SpringOne Platform 2016

What is a documentation architect?

When I was at Write the Docs 2015, several people asked me about the title I have in my LinkedIn heading: Documentation Architect.

What did I mean by that? How is it different than content management or development architecture?

What a documentation architect isn’t

A documentation architect isn’t psychic. They can’t figure out your business needs unless you tell them.

They aren’t necessarily managers. They are designing the documents and process, not the team to build out the documents.

They’re not community managers. That’s a underrated specialty that combines amazing amounts of patience, charm, and detail-orientation. You should have a community manager, but it’s very difficult to combine with document architecture.

It’s not data architecture. The positions seem superficially related, but in this sense, data is the communication software has with itself and other software. Documentation is the communication software has with humans.

What a documentation architect is

Technical writing, like most jobs, is a combination of disciplines in different proportions. I can set up a documentation set, choose a documentation tool, predict usability pitfalls, monitor a translation agency, and conduct user testing.

I also have some less tangible, but equally important skills for building an organization’s first documentation set. I have enough moxie to tell people they are slow in getting their documentation going. I have seen enough successes and failures to have design models for several delivery methods across several industries. I can extrapolate from meetings what is most likely to need documenting in a month, or three, and what we should do about that.

Much like a software architect, I can build something novel, thought-out, and designed to guide less-experienced creators to assemble a product that will succeed over a period of time. Also like a software architect, I need to understand both the business needs of an organization and the skill sets required to accomplish my goal. I’ve come to realize that this form of architecture is about systems thinking and how the pieces come together to form the whole.

The other aspect of my specialty is experience. I don’t just understand technical communications problems intellectually, I have failed and succeeded at almost every type of project you can name. I’ve been doing this for long enough to know the failure modes of so many more projects than newer writers can have had time for. I also have had enough experience in different fields and organizations that I can identify nuances that more settled writers have not been exposed to.

When you are looking for a writer, or a user experience designer, or a developer, ask yourself if you are interested in someone who can learn and grow with your product, perhaps with a little guidance, or whether you are looking for someone who can understand and build aspects of the product in partnership at a higher level. Making that distinction will save you a lot of time both in the hiring process and when you are working with the new hire.

(cross-posted from LinkedIn)