How Much Code Should I Know?
- David Dunn
- Mar 29
- 5 min read
As a software technical writer, you help users navigate software. You may feel lost yourself, though, without a developer to guide you. Everyone needs occasional guidance, but the more guidance you receive over time, the more you should be able to offer. If you learn to read or even write code, you can help developers stay focused, or maybe even teach them something!
This article contains links to Wikipedia articles for more information. Links do not point to product websites at this time.
I Already Learned One Language!
If you are a technical writer with an English background, software might intimidate you. You spent over 20 years mastering (or at least bachelor-ing) one language, and now you're surrounded by developers who can also speak C++, Python, or maybe Rust. Even the names sound alien! If you are a beginner, you may wonder how you'll ever find your bearings. If you are in the middle of your career, you may ask, "Do I really know enough?"
What is My Goal?
To advance your career, you need to lift up your users without tearing down your developers. Learning to read or write code can help you answer user questions without having to spend as much time consulting developers. The sections below describe user groups and languages that can help you serve them.
All Users
Language Purpose: Text structure and format
If you author content with a tool like MadCap Flare, Adobe RoboHelp, or WordPress, languages like HTML and CSS can help you format content quickly, correctly, and consistently.
The code block below provides an example HTML file.
<html>
<head>
<title>Dunn Family</title>
</head>
<body>
<h1>Dunn Family</h1>
<p>David, Missus, Big Brother, and Little Brother. </p>
</body>
</html>This example would let a web browser know that the title bar should display "Dunn Family," and the content window should display a heading with the same text, and a paragraph that lists the family members.
Languages like Markdown provide minimal format options, but writers might have an easier time learning to use these languages. Many development projects embed Markdown files in the project. Developers and technical writers can coauthor documentation in these environments without the burden of extensive training.
The code block below provides an example Markdown file.
# Dunn Family
David, Missus, Big Brother, and little brother.This file would display the same content as the HTML file, but only if you view the code through an interpreter. If you open the file without an interpreter, it displays identical to the code block. Luckily, you can usually read Markdown code clearly on its own.
When you learn a language that helps format or structure documents, you become a subject matter expert within your department. When your team needs new templates or runs into a bug, you can help prevent a bottleneck in production.
Integration Users
Language Purpose: Configuration file
Integration users make software ready for end users. Integration commonly includes installation and configuration. Languages like XML, JSON, and YAML provide easy to read structures for humans and computers. The code block below provides a JSON configuration file example.
{
"Family": {
"Name": "Dunn",
"Members": [
"David",
"Missus",
"Big Brother",
"Little Brother"
]
}
}If you wanted to reconfigure the system in the code above, you could substitute "Dunn" with your family name and delete or add "Members" to the list as needed.
When you learn how to interpret configuration files, you can create configuration documentation with less SME intervention from developers. Your team will appreciate that they can increase focus on their core responsibilities.
Development Users
Language Purpose: Programming
Examples: C++, Python, Rust, C#
The languages presented so far have taken text or values and used them for display or operation. Documentation and configuration settings should last for a while unchanged. Developers also use languages that constantly interpret and transform data many times. These programming languages can be useful to learn to read, if not write, when you make documentation for developers.
Development teams often leverage technical writers to document APIs. These provide connection points that allow one program to communicate with a separate program. An API might receive the same data the JSON configuration file data listed in the previous code block. The C# code block below represents how a program might structure this data.
namespace MyCompany.MyProgram.API
{
public class Family
{
public string Name {get; set;} = "No Name Given";
public List<string> Members {get; set;} = ["N/A"];
}
}This content does not immediately appear as straightforward as previous examples. The code sets up a class which acts as a template for "Family" objects. The class can get or set a text string value for "Name" or a list of text strings for "Members." Additionally, the class provides default values in case the interface user does not specify a value. If the API does not receive a name, the class defaults to "No Name Given." If the API does not receive a members list the class "Members" value defaults to a list with one member, "N/A."
When you learn to interpret programming language, you position yourself to become an SME for developers. Earlier in your career, you likely relied on the development team to constantly explain software to you. As a technical writer with development knowledge, you may be able to return the favor for them.
Where Do I Start?
If you don't have a lot of experience with code, your head may be swimming. If you feel intimidated by all these languages, you have nothing to worry about. You have already started to learn! If you want concrete steps, consider these:
Ask your manager if your team uses a content tool that uses a markup language.
Ask your development team if you need to document configuration files or APIs.
Ask which language the tool or files use.
Ask if your company provides access to courses that introduce these languages or documentation types.
Look at existing company documents as examples.
Finally, to answer the question, "How much code should I know?" simply take one step at a time. Determine what type of user you need to help and learn more and more how to help them. As you learn, you will open doors to new opportunities, and you can get as deep into the code as you want. Remember, as a technical writer, you probably weren't hired because you know how to code. The unique talent you bring is your ability to understand your audience and point them in the right direction. Everything else you learn is value that compounds upon the talent you already have.
Comments