The Art of Writing Documentation and Other Technical Content

Let’s cut to the chase – when learning how to become a better Developer Advocate, Technical Influencer, Teacher, Documentation Writer, Technical Thought Leader, writing documentation, or just generally trying to better communicate about technical material, you're going to struggle over the balance between verbosity and context.

It doesn’t matter what medium you’re communicating through, be it software development documentation, a blog platform like Dev.to or Medium, or even something as simple as a Readme.md file in a source code repository. The amount of thought, planning, research, draft work, and prototyping that goes on behind the scenes is tremendous, yet often unnoticed and underappreciated by your readers. When done “well,” the audience gets a nice and “concise” bit of technical content that, at a glance, makes everything seem like magic, and of course “very doable.”

All said and done, you – as the publisher of this content – think, “Ahh, everything is great…time to send this beauty of a piece out into the world.”

It is great… until you’re on the other side of this author-reader fence, where you find yourself neck deep in 30 Chrome tabs, “console.log(‘Please Print 🙏’)” in every function in your editor, and nothing but bright red stack traces every time you hit debug. Of course then you have the end of day thoughts: “How did they make it look so easy?”, “I really hope someone replies to my issue on Github” and “I hope I didn’t sound like an idiot in my Stack Overflow question”. Hello, compounding stress of imposter syndrome and ever approaching due dates!

So – let’s take a step back here. What’s missing in this cycle of asynchronous knowledge transfer from author to reader, teacher to student, influencer to audience, creator to consumer, and researcher to implementation engineer? How can you ensure writing documentation or other technical content for your product will lead to a happier audience and fewer questions?

It’s a Simple Problem: Context is sacrificed for Conciseness

The most informationally dense and valuable part of content authorship, the creative process, the personal deep learning that drives true understanding and detailed re-explanations, the nuance, the iteration, the workflow, the “why and how” is lost upon publication, all in the spirit of “conciseness”, “approachability”, and attempting to communicate “what to do”.

But this is a lose-lose for both the author and the reader, as the purpose of writing technical documentation, guides and other materials are to provide rich detail and context so your readers can follow along and extract essential information - not to summarize key points, which can lead to frustration and loss of credibility from your audience.

If you’re still with me… read on to learn how to write technical documentation that will not only attract users, but guide them to their end goal. This blog post will not only change the way you publish technical writing and documentation, but also the way you share and reuse it within your team and amongst your audience.

Technical Authors are Technical Readers

Technical writers begin their authorship process with the goal of enabling readers to create technical things, and in that goal, they themselves must understand the material deeply. For example, technical documentation writing often requires the author to fully understand and aggregate information from various other sources, including docs, frameworks, and libraries involved in the project.

This falls directly in line with the classic saying, “While we teach, we learn.” - Roman philosopher Seneca.

But the downfall of great developer advocacy is expecting the reader to understand hidden information, leaving your audience to search for the missing ingredients of what seems like a simple recipe to the writer who has undergone comprehensive research and doesn’t bother “wasting time” getting into the details.

As an author, perhaps you start with an outline or essence of what you want to communicate, but as with all technical roles, you quickly transition to the “what can I google” and “who can I talk to” part of your process.

A “let’s settle this once and for all” example.

You’re doing a good ol’ code review on a Pull Request for your company's web app, and being the elite developer that you are 😉, you comment on the usage of loops in your colleagues code… Queue the onslaught of relentless Github and Slack notifications.

Next thing you know, you’re writing an article and/or a refactoring memo about loops in Javascript, and of course it’s covering all of the classic questions: Which loops are the fastest? What’s the difference? When do you use each one? Which ones support asynchronous iteration? Which ones support yield iteration with generator functions?

Oh, and we can’t forget – because we are in an era of the “world wild web”, we should obviously mention browser support, nuances when used in node.js, and for all of the Typescript developers out there, “How do you strong-type each of them?”.

The end of the debate begins with several succinct snippets of code

A couple of days go by, and you have completed a kick-ass and comprehensive overview of loops in Javascript/Typescript. Your article contains seven or so code snippets to run, benchmark and output the performance results for each of your examples.

Great… you proved your point, earned some street cred, and got a nice content piece published out there on the interwebs. What’s next? An influx of questions and comments typically along the lines of: Do you have any other resources where I can learn more about these things? Where can I find an example of this in the code base? What’s the difference between async iteration and generators? Why did you use “Performance.now” instead of “Console.time”?  Where is the original Issue or Pull Request outlining this refactor? How does it transpile in Babel from ESM to ES2015? What site did you use to look at browser support? Do you have an example from the Typescript documentation?

Writing effective documentation leads to fewer questions asked

The point here is that – most of these questions – you have already Googled, researched, thought through, prototyped and answered; however, the problem is that riiigggghhtttt after you clicked publish, you went straight for the “Close all Tabs” button, had an awesome feeling of accomplishment and completion, and then proceeded to lose the most important part of your authorship: the context, aka your work in progress.

With the loss of that context, you lose the relationships between the sites you visited, the tutorials you watched or read, which code snippets came from where, who you talked to, where you found the example code in production, the other similar blog posts that you may have gotten inspiration from, and so on. The list not only goes on, but also becomes even more disastrous as the complexity of your content - and the depth of needed background - increases.

So - having given the people what they want and authentically engaged your readers, you now find yourself scrolling through your never-ending browser history, looking for one of, now many, approved and merged Pull Requests in an effort to reference the code as it was before, trying to figure out how to use the search functionality in the never ending stream of chaos that is Slack. 🙃

Oh, and if you’re like me, you probably didn’t take the most extensive notes, you probably didn’t save every iteration of your prototypes, you probably didn’t title every snippet, tag it, describe it, capture where it came from, and who has contributed to it… The likelihood that you did all of this is probably low (and that’s okay, I am guilty too!).

But, say that you were the best organizer in the world, and you did all of this organization in your favorite markdown editor, or note-taking app… at the end of the day, you’re still at the mercy of how good the tools search is and how accessible those materials are from within your workflow. Unless, of course, you’re an avid Pieces for Developers user and leverage AI-powered Auto-Enrichment to save useful information about your materials, and Global Search to find them 😎

The Tipping Point 😤

If you can’t tell by now, I’ll just say it outright: as both an author and a reader of developer documentation and other technical content, the way these materials (code snippets, screenshots, diagrams, text notes, links, etc.) are shared, saved, searched, and reused throughout the end-to-end authorship-readership exchange has traditionally been pure chaos.

This is a lose-lose situation for both authors and readers. The authors bear the burden of doing all the work writing good technical documentation, and the readers who want to really learn and dig in deeply lose out on benefiting from the author's knowledge and effort.

When all of this context is distilled away and disconnected from the final draft and its components, the reader is too often left with more questions than answers.

The frustration of not being able to put the author’s technical documentation writing fully into practice without extensive research is such a problem for readers that the team at Pieces (myself included) has built an awesome solution to developer workflows that address these exact struggles.

As a reader, what does this look like in practice?

Let’s look at some good and bad technical writing examples from an existing article; one of the many articles that inspired me to write this blog post:

“Measuring Performance of Different JavaScript Loop Types” by Chameera Dulanga (700+ Claps | 3K Followers on Medium | Software Engineer | AWS Community Builder | Content Specialist)"

Side note: Before I get into it, Chameera, thank you for writing this post and publishing this content and teaching others. My intent here is to highlight how your authorship experience and your readers' experiences can be nicely enhanced by enriching your code snippets with more context, as we’ll review in this article.

The first thing you’ll notice above is a nice overview of How to Measure the Performance of Code accompanied by a nice boilerplate snippet and some commentary.

As I read this first section, a couple of things come to mind:

• Should I save this boilerplate snippet? Might be handy...

• What’s the difference between “console.time” & “Performance.now”?

• Where can I learn more about Measuring Performance in Javascript?

• Do both work in the browser and Node.js?

• Why did he opt out of one and not the other?

• What's the optimal “purpose” for the one he opted out of?

• I’d love to share this article with my team, but that’s going to cause me a bunch of problems because I’m probably going to get many questions the author didn’t answer… I should probably Google them.

It’s up to the author to think about the questions a reader may ask while researching and organizing contents for their technical blog writing. Providing essential context will empower the audience to take a more reasonable approach to solving the project the author is writing documentation about.

One suggested technique to improve this workflow is using Pieces to save and share materials with related context (tags, related links, description and more) in a single click. Before we built Pieces, the process of saving and organizing that boilerplate snippet was a multi-step, multi-click, multi-app process. Now, if authors leverage Pieces to share links like this one in their various types of technical writing, readers can reap the rewards of deeper understanding and context for more efficient problem solving with their team.

Expecting readers to Google, save the links, and take notes on questions would take time and probably wouldn’t be from the same sources that the author visited.

The app that I took notes in was different from where I stored my code snippets (I would add them to IntelliJ/VS Code Snippets), and so the explanation would be separated from the solution and source.

If you asked me to find this or share it later on… Well, you would get something back like “You’re probably better off Googling it yourself,” or “I have no clue where it might be on my computer, hang on,” or even “I’m on crunch time, I can’t help you at the moment but ping me tomorrow.”

The summation of all of this friction would amount to me simply not taking the time to do any of these things in the first place. 🤫😬

Getting further into the article there are more code examples, descriptions, and also some really great performance charts:

By the time I am finished with the article, I have a bunch of questions, most of which I didn’t take the time to look up, and similarly, I also wanted to save a bunch of things for future reference or so I can share them with my team when needed… but probably didn’t end up taking the time.

How does Pieces for Developers make you a better Technical Reader… and in turn a Better Technical Writer?

We built Pieces to help developers save, enrich, transform, search, reuse, and share snippets, and our users tell us they find the context of the snippet as valuable as the code itself - the URL or file the snippet came from, the natural language tags or description related to the snippet.

As it turns out, this context is the key to making technical content for engineers much more impactful! Let's dive in deeper on the solution:

What does saving a snippet (or pasting a screenshot) look like with Pieces?

You may have noticed the “Save” button in some of the screenshots above. Here is what happens when all you do is click that button, and nothing more:

1. Pieces noticed that you just saved some text

2. It auto-magically determined that what it received wasn’t simply text, but was actually code

3. Pieces saves the snippet to your Pieces micro-repo and titles that code for you, identifies the language, and makes it look pretty with some syntax highlighting

That’s not all… when you navigate to the information view in the Pieces app [ ⌘ (macos) or ^ (windows)  + i ] you will notice that Pieces also did the following:

1. Added a relevant smart description for the snippet

2. Auto-magically tagged the snippet as being related to node.js and javascript

3. And lastly, it captured the URL source of the snippet as a related link from Chrome

Pieces has not only made it incredibly easy to save content from your technical reading, but also captures, organizes, and enriches the material with as much context as possible.

As a reader, what about the questions that I was thinking about while reading the article? Pieces made it super easy to add even more custom context.

I can easily add or edit related links, tags, the description, sensitive information, and any other information the author may have left out when writing documentation, all with a few common keyboard shortcuts. Appending additional context for myself and my teammates can be a huge timesaver when reusing and sharing snippets.

And, of course, I can also save the snippet that I found comparing “console.time” & “Performance.now” on Stack Overflow when I did my additional research as a reader… and you guessed it – Pieces already knew that those two snippets are highly related to each other.

What about the charts from the article, or perhaps screenshots from a youtube tutorial on loops? Those materials are also super easy to save, search for, share, and even extract code and text from as an author or reader.

In this case, Pieces’ optical code recognition software noticed you saved an image, processed that image, determined it contained Typescript, and did the rest of its auto-magic.

As a reader, you no longer have to rewrite the code in this image manually. Or, as an author, you can take the extra step and convert your screenshots to code so your readers don’t have to. Technical blog, manual, guide and documentation writing just got a whole lot friendlier.

It doesn’t stop there… What about using snippets while prototyping?

All you have to do is open up your favorite editor, such as IntelliJ or VS Code, and simply start typing. Pieces will auto-complete your saved snippets directly into your editor.

And if you quickly need to look something up, be it online or offline, you can search everything you just saved from your reading without ever leaving your editor.

Technical writing tips from our previous example

Writing technical documentation and other content with Pieces is a game-changer, as it fundamentally unlocks the best of both worlds, allowing you to achieve both concise and context-rich content.

Turning a focus back to the initial blog post on Javascript Loops - there are a few things that Chameera Dulanga can do differently with Pieces.

As he goes through his content research, curation, and production process, Chameera can use Pieces as a reader to automatically capture the deep context of his workflow, i.e. snippets themselves, diagrams, related links, tutorials, inspiration, descriptions, etc.

In doing so, he has now associated all that captured context with the final snippets he wanted to include in the article.

Now, for each snippet in the article, Chameera can create a shareable link from his personally branded Pieces cloud and perhaps add it to the title of each snippet and/or diagram.

What happens next is a magical bridging between authorship and readership…

If Chameera were to publish content where each snippet/diagram/image could be saved via a Pieces link, the only thing a reader using Pieces has to do is simply click that link. From there, the snippet and all its glorious context is automatically added to their personal Pieces micro-repository.

Finally, readers can save, search, revisit, reuse, and share content from developer advocates and other technical authors without ever losing the context.

It’s Pretty Cool. Try it out yourself.

Save a Javascript Snippet from our collection! (Or… click this link to save this piece! → Javascript Loop Perf Snippet - For/Of )

Okay great - so as an author, I can now share the snippet or image with all of its context through a single click from the reader… What if they want to save all materials?

No worries, starting with the release of Pieces 1.7.0, authors can work with the Pieces team to curate and distribute a collection that goes along with their technical content.

This now allows developers using Pieces, still with a single click, to seamlessly save a collection of many items, i.e. snippets, diagrams, links, text notes and images (with all of their context), directly into the reader’s Pieces micro-repository. (Side note: email us at support@pieces.app to become a pilot author!)

Curated collections are available today and you can explore the magic directly on the Pieces website!

Ready to write documentation for your audience?

The relationship between authors and readers, especially when it comes to writing technical documentation, is delicate, and there is a fine line between oversharing the context of technical content and maintaining the perfect amount of brevity and readability.

The team here at Pieces is working on enabling experiences that maintain this vision of concise authorship & contextual readership. Further, the team is deeply interested in raising the bar of expectations around saving, searching, sharing, and reusing the most important parts of your technical processes.

Hopefully, you got a sense of the new techniques Pieces enables to dramatically improve the experience of publishing and consuming technical content.

We believe that Pieces is off to a fantastic start reducing friction in a research or publication workflow, and we’re excited to look at how Pieces continues to reduce friction when writing code, collaborating with other team members, and discovering work that has already been done or may be deeply related to what you are currently doing.

We would love it if you joined us on this journey to help make Pieces the tool that every developer never knew they needed, but eventually won't be able to live without. 🤘

If you’re wondering how to leverage AI in technical writing for a brand like Pieces, join our content partner program and help us write amazing technical content for our blog!