Photo by Anika Huizinga on Unsplash
The scene: Your product has dependencies on a third-party tool and your users’ success depends on how well they use this tool.
As the users’ advocate, where should you draw the line between your documentation and third-party documentation?
Writing Inside the Lines
When I started writing, company policy dictated that we only document stuff built in-house.
I didn’t question the policy because it made sense. Our small-but-capable team documented a complex, sprawling, and innovative collection of financial technology. Sure, our users needed to know Java and database management, but neither Sun nor Oracle paid us to write documentation. My coworkers, my tech-writer friends, and I, we all scoffed at the idea of writing documentation for other companies. If we could trace a support ticket to a third-party, we could confidently declare “RTOFM” (Read the Other F***ing Manual”).
Our policies and attitudes made sense based on the assumptions we made about our products and users.
The other doc is sufficient.
Those third parties were massive companies who provided massive documentation with their products as a matter of form. Why waste our time rewriting someone else’s doc?
Products are black boxes.
The closed, proprietary systems in the technology stack gave us obvious boundaries to segregate our stuff vs. their stuff for support and documentation.
Our users are experts.
We assumed that our users already knew the business domain and the full breadth of the technology stack. Our business model reinforced our assumption. We hunted the big accounts, the whales, the few high-margin customers, staffed by seasoned users, who could single-handedly tip the balance sheet into profitability. In the long-tail distribution customer model, our prey all clustered at the head of the curve. We didn’t have the resources, technology, or mindset to sift for the meager returns in the long tail of the curve.
No surprise, our assumptions were often very wrong.
The other doc is sufficient.
Reality: The third-party doc was massive, but it was also often general reference, ineffectual for our users who needed specific, practical solutions to their unique issues. Directing our users into third-party doc in their moment of need was like responding to their questions about ordering breakfast in a restaurant by pointing them at the Oxford English Dictionary.
Products are all black boxes.
Reality: Here the assumption was correct, but led to the wrong results. The obvious divisions between the black boxes in the tech stack gave us natural boundaries for our content along with a false sense of security. As long as we produced thorough documentation on our side of the boundary, we could rest in the knowledge that we’d done our job. But was our job reinforcing what’s ours and what’s not or was it making sure that our users succeeded?
Our users are experts.
Reality: Our users were always less informed and less experienced than we assumed, even at our largest, most well established customers. Our business innovations required leaps in understanding grounded on a strong foundation in domain knowledge, which our end users often lacked. Our bleeding-edge technology solutions demanded thorough knowledge of the latest technologies and standards that were sometimes still evolving. Our own developers were often still learning the technologies and interpreting the standards as they went. If our own developers weren’t experts, then why did we expect our customers’ developers to be? Of course, end users and customer developers demonstrated the gaps in their knowledge and understanding with the support tickets they generated.
The Situation Now
If our assumptions about third-party doc were incorrect in the past, they are even more off the mark now.
The other doc is sufficient.
Now: Today’s tech stacks comprise a smorgasbord of tools and technologies, some proprietary, many others rooted in open source projects. You may find little documentation depending on a project’s maturity and adoption, and that doc might be difficult to access: embedded in the code, captured in readme files, spread across various extensions and modules, or buried in a user forum. Stack Overflow is a great resource, but do you really want to abdicate control of your users’ experience to a question and answer website?
Products are all black boxes.
Now: Each layer in the tech stack can be less an inscrutable black box and more a toolbox that enables the user to experiment and improvise their own solutions. Consequently, the boundaries between the layers grow less distinct as the possible combinations of dependencies grow between them. For the writer, this calls for a holistic approach to documentation that includes those third-party products.
Our users are experts.
Now: Current business models swap the traditional target demographic of the long-tail customer model from the head to the tail, leveraging technology to extract value from the long tail. Your target user isn’t just the bigwig at the head of the curve, but any of the heterogeneous user personae in the long tail. Your challenge is to provide a successful experience to them all and it’s likely many of them need guidance with third-party products.
An Answer
So how do I draw the line between documenting my stuff and third-party stuff?
I don’t have a prescriptive answer. The complexity of our work precludes something so tidy. Instead, I just work through my original assumptions:
The other doc is sufficient.
It might be. It might not. Do your research. If someone else has already answered your users’ question, how accessible are the answers? You should make the effort to put that content where your users need it.
Products are all black boxes.
Even if your product is a discrete, closed system with well-defined inputs and outputs (an actual black box), even a black box is seldom used in isolation. You have to answer the same questions as the writers whose users can pop the top off the box and play around. What are your dependencies on third-party systems? How do these dependencies affect the user experience of your product? What control do users have over the external dependencies and what do they need to know to control them?
Keep in mind that, as you address these questions, users don’t care where you think the line is. If you are the product or service provider, they expect you to provide a successful experience.
Our users are experts.
Who do you write for? Your beginners might need fundamental info about your business domain and your underlying tools and technologies. I find these topics usually well covered in third-party sources. You also need to ensure that your experts who ask specific questions and work on innovative solutions don’t have to wade through beginner content to get the answers they need. You might have to get as creative and innovative as your expert users in integrating third-party information. And while you’re focusing on your users, the greatest challenge is to provide an experience that fosters a productive, ongoing relationship. You want each of the users in the long tail to feel as valued as the whales at the head.
A Typical Case
I’m setting up a static site generator (SSG) for internal doc distribution. This is my first SSG and I’ve had some early success, which I owe entirely to the open-source pioneers who have gone (and documented) before me. Now I’m adding some flourishes like full-text search for our PDF repository with the Elasticsearch engine.
I’m leaning heavily on Elastic’s doc. Luckily, it’s excellent. One doc feature that stands out for me as I work with their RESTful API is the “copy as cURL” button included with every API endpoint example. One click and the example moves to my clipboard, right where I need it, right where I can paste it into the command line.
I know how to use cURL. Despite sophisticated tools like Postman, I still use it when I’m neck deep in the command line. So I’m not a cURL beginner. Just about everything else is new to me though, so I really appreciate the convenience of prepared cURL examples baked right into the doc, exactly where I need them and not squirreled away in a reference section or behind a link.
I’m solidly in that long tail of the customer curve: an ambitious beginner. I haven’t paid Elastic a cent. Elastic could’ve easily punted with a prerequisite like: “You need to know how to use cURL.” Instead, their documentation makes it clear that they value my success. I feel catered to, just like the bigwigs at the head of the curve.
And that’s our goal no matter where we draw the line: successful, even delightful experiences for all users along the curve.
You may also enjoy:
Getting to Intuitive: A Good User Experience (UX) Relies on Technical Communications
Content Strategy Intersects with Technical Writing & User Advocacy
