How do I develop documentation skills for my tech career?

Is this what your team's documentation looks like?

Photo by Cristina Gottardi on Unsplash

Imagine you're staring at the codebase, wondering why another dev, a year ago, made a coding decision that makes no sense. Maybe you're watching a user interaction on your app, the user getting confused, and no one can tell you why it was designed this way.

Documentation might sound abstract and irrelevant, but no matter your role or level - developers, product, design, user experience, machine learning scientists — everyone can benefit from creating and using documentation.

Learning how to write documentation and how to use (and not use) AI for writing documentation can help you grow in your career and solve your team's problems.

People

Actual humans will be working on your products in the future, including you and your coworkers! I can't count the number of times I looked back at code I wrote only a few months earlier, scratching my head thinking, "Why did I do this? Why did we make this architectural decision? Why didn't I write a test to cover that case?"

Future you will thank you!

Photo by Vitaly Gariev on Unsplash

Promotions

Documentation includes writing down all your accomplishments! And that can help you write your promotion document when you're ready for that next step. Not to mention that showing off the documentation you've created for your product or code can help with your promotion chances, too.

Products

When I took the time to describe test cases, I was able to solidify the product requirements before I even started writing code. If you document from the beginning, it provides you with questions for engineers, product, design, and other stakeholders and saves you time by preventing unexpected changes at the end.

Documentation is all about:

What to Document

• Design conversations

• Product requirements & decisions

• Notes from meetings

• Architecture designs

• Onboarding instructions

• Proposals

• Goals from 1:1s with your manager

• Weekly accomplishments for promo docs and your resume

• Recommendations from your managers or coworkers

Where to Document

• In code (comments and tests)

• Github or Jira for issues

• Shared documents (Coda, Notion, or Google Docs)

• Slack canvases or conversation threads

• AI prompt files

• Figma designs

• Internal wikis

• That random text file living on your computer

• Videos

Ok, let's get into it! How do you even write documentation? Well, every role, tool, and topic has different styles or requirements for how to write the documentation. But there are a few commonalities:

• Think about your audience. Who are they? Are they technical or non-technical? What are they trying to accomplish by reading this document or watching this video?

• Ask AI for suggestions on how to organize or format specific types of documents.

• Include links to related documents.

• Check out examples of existing documents your team has. How can you follow those formatting rules and maybe even improve on them?

• Update existing documentation first. Try to find docs your team already has. Create a new document if you're sure there isn't already documentation for this topic.

Quiz

At the end of a team meeting, your manager asks you to document the decisions made about the design of a new feature. You know that there's an existing product document in Microsoft Word for this feature.

How should you document the decisions?

A. Ask AI to write a few paragraphs about the decisions in the existing document.

B. Create a Slack thread summarizing the decisions and include a link to the updated documentation.

C. Ask AI to give you ideas about how to format documentation for the feature.

D. Create a new Slack canvas for the decisions summary.

By the time you finish reading this sentence, there will be three new ways to use AI to help you on the job, including writing documentation

It's important to use AI intentionally. If AI writes all your documentation for you, you won't benefit from thinking through constraints, asking questions, or using critical thinking. Plus, it will be harder for others to use. The exercise of planning, writing, revising, and getting feedback on documentation helps you grow other skills, understand your products and users, and identify gaps and opportunities.

You can decide how and when you want to use AI for documentation. Some ideas include brainstorming, finding sources and related documentation, and formatting and organization suggestions. Make sure that whatever AI tools you use are approved by your company.

AI can be a useful tool, but don't let it make you worse at your job or lose your connection to other people!

There are times when a "set it and forget it" attitude in tech works. But for documentation, you need a collaborative, "living" document that's easy to find and up-to-date.

Ask yourself:

• Where does the document live? Decide with your team where to keep documentation. The fewer places (wikis, Slack, Microsoft Word) you keep your documentation, the better. No one wants to wade through multiple tools trying to find last week's meeting note.

• Who is involved? Mention people in the documentation. This keeps conversations going in the documents, and reminds people that it exists.

• Where is it? Make sure the documentation is in the cloud, not on any one person's laptop.

• Who wants to know? I think of this as advertising. When you update or create any documentation, share the highlights in Slack or Teams. Make sure that your manager knows about it, too.

• Leave it better than you found it. Anytime you use existing documentation, find a way to improve it!

Ready to put your documentation skills to work?