So, how do technical writers fill the knowledge gap? That’s where Subject Matter Experts (SMEs) come in. Working with them is one of the key functions of being a technical writer. And, if properly handled, it is one of the most rewarding and fun aspects of being a technical writer.

What is an SME?  

Subject Matter Experts have advanced knowledge and specialized skills in a specific field. For example, when it comes to software engineering, an SME may have advanced knowledge in Android development, iOS development,  machine learning, and so on. They are authorities in a specific area, so they are qualified (and often asked) to give guidance around strategy, uses, implementation, and learning in the field in which they’re an SME.  

They’re needed and used in a wide range of industries, from technology to energy to chemicals to transportation, and SMEs remain SMEs by continuing to grow and learn in their given field. An SME is an industry-agnostic role and concept, but we often see them in technical fields. As a technical writer at a tech consulting firm, the SMEs I engage with are usually focused on software engineering.  

Why do technical writers work with SMEs?  

To be a technical writer is to be curious. And with that comes the endless desire to learn. As technical writers, we are constantly learning. We are brought in to document things we are familiar with but not fluent in. Luckily, there is often an SME who is fluent in what we, technical writers, are familiar with and tasked to document. Enter the SME/technical writer pairing.  

These pairings are used on various projects—from internal work to user-facing work and consulting. A technical writer and an SME are paired to fill knowledge and skill gaps. An SME might be an incredible engineer but lack confidence in their writing abilities. As for the technical writer, they might be an amazing writer, but their hard engineering skills might not be at a high level. Thus, the technical writer and SME combine to fill one another’s knowledge and skill gaps. Through doing so, they offer a lot of value and bring a lot to both their work.  

For technical writer and SME pairings to do stellar work, they need to know how to best work with one another. I can only speak to this from a technical writer standpoint, but the tips I will share go both ways.  

How to work best with SMEs 

Communicate early and often. 

This tip sounds a bit obvious, but in the fast-paced environments we often work in, communication can fall by the wayside. So, be intentional about communicating with the SME(s) that you work with—whether that is asynchronous communication through Slack and email or in Zoom and in-person meetings—and always leave ample time for discussion before any work is due. And what I mean by that is to bring to light any concerns, gaps in knowledge, potential blockers, and more before they become issues that could slow your work down or hinder your work in any way.  

Be kind.  

Once again, this might sound obvious. But friendliness goes a long way! A technical writer’s relationship with an SME is often somewhat one-sided insofar as we often ask way more of them than they do of us. From questions about new API changes to double-checking basic code snippets we write, SMEs do a lot for us. So, it is essential to be kind. And better yet, get to know them on a personal level. This is important with any coworkers, but the ones you work the closest with should be individuals that you can get to know on a personal level.  

An SME is not a walking knowledge bank. Don’t treat them as such, and don’t reach out only when you need help. You likely have shared interests and commonalities. Get to know them, and you never know. You might make a new friend or mentor.  

Ask questions.  

As a technical writer, you need to ask your SME(s) a lot of questions about what you’ve been tasked with documenting. This is because you need to translate the knowledge that lives in your SME’s head into consumable words. People say there is no such thing as a bad question, and while that is true, there are bad ways to ask questions.

It is also important to do your homework before asking questions. For example, if you have a question about a code snippet an SME passed to you, run it in an IDE first to get a better understanding of it before you ask your question. A little legwork can help you answer your own questions. Ask questions clearly, break a question into multiple simpler questions if it is complex, and ask them in such a way that you and an SME can work toward an answer together.  

Knowledge transfers between an SME and a technical writer often start with the technical writer asking questions or reaching out for guidance and support. This is important because SMEs can teach us so much and asking active questions (where examples can be created or talked through) is a great way to learn, and important questions should never wait. Waiting until the last minute to ask an SME about a project-related question puts undue stress on them to get you an answer immediately, and rushing to an answer or teaching something rapidly might not lead to the best solution. Be diligent, timely, thoughtful, and thorough with your question-asking, and SMEs will repay you with brilliant answers and knowledge transfers.  

Be transparent about skillsets and boundaries.  

A technical writer and an SME should always be open and honest about their skillsets and the places where they may start to feel out of their depth. This also applies to roles and responsibilities. There might be some overlap between tasks between a technical writer and an SME, but letting one another do what they do best and not overstepping is very important. You’ve been paired together for a reason: to highlight one another’s strengths and fill in one another’s weaknesses.  

Openly discuss and share these strengths and weaknesses so you and your SME know how to best work with and support each other. Knowing your strengths and weaknesses, you can do your best work together. And more importantly, you can start learning from one another. An SME and technical writer pairing is as much a soft mentorship as a business practice. Make the most of it.  

In conclusion 

As a technical writer, being paired with an SME can prove to be one of the most fun and fruitful experiences in your career. You need to be intentional about how to go about that experience, and I’ve shared some tips on how to make the most of it. Any project where I am paired with an SME is a joy for me because I get to learn from the best while also doing impactful work.

Next time you find yourself working with an SME, try these tips. They will help you build rapport more quickly—and collaborate more effectively.  

The post Technical Writing 101: Working with SMEs  appeared first on Big Nerd Ranch.

What is Markdown?

Markdown is a lightweight markup language created in 2004 by John Gruber and Aaron Swartz. It creates formatted text via a plain-text editor. Unlike HTML or XML, it is still easily digestible by readers of all backgrounds in its source form. You don’t need to be a programmer to get the gist of things. And although it borrows its syntax from HTML, Markdown is easier and quicker to learn.

The tags—that is, the syntax used to format text (<b>word</b> to bold text, for example)—are simpler than HTML, but they still automatically convert to HTML. So, if you’d prefer, you can still use HTML tags when working with Markdown.

Markdown is used almost everywhere, from GitHub to Slack. It’s the unofficial text writing and formatting standard on big coding sites, like coding repositories. Most engineering readme files are written with and formatted using Markdown. Most text editors accept it as well.

Beyond the fact that it’s easy to use, quick to learn, and easily converts to HTML, Markdown is also pretty futureproof. By this, I mean Markdown will be usable as long as plain text is the official and unofficial standard. It was designed to be quickly parsed and digested as a raw file, but also has its own file extension (.md). Suffice to say, Markdown isn’t going anywhere—especially in the world of engineering and engineering documentation.

Why use Markdown?

I’m answering this question from my perspective as a technical writer, but you can leverage the benefits of Markdown whenever you write online.

1: It’s simple

Markdown is very simple, as far as markup languages are concerned. That is honestly its biggest benefit. It takes maybe 30 minutes to learn and about an hour to become proficient. Another added benefit both within and outside of engineering orgs is that Markdown text is easy to parse and read in its raw form. This is important because both XML and HTML have a learning curve, so folks who aren’t versed in those languages might not be able to read text packaged in either of those markup languages. Markdown fixes that. It is unobtrusive to the actual text so anyone can read text packaged within Markdown’s syntax.

2: It’s a soft introduction to programming

If you’re new to the world of software engineering, Markdown works as an interesting peek into the power of code. Yes, Markdown’s syntax is simple, but if you’ve never coded, even formatting in Markdown might feel like coding. Seeing your formatting come to life on a webpage or text editor is very cool for those new to programming or markup languages, and I firmly believe that it can inspire people to dive deeper into the world of coding.

3: It’s fast

Now, from a technical writer’s perspective, Markdown makes my job easier. I can write with Markdown at a faster cadence than I could with HTML or XML. Plus, I’ve found that Markdown has been an invaluable bridge between engineering and content writing (a massive umbrella that technical writing falls under).

If a subject matter expert (SME) hands me a piece of documentation he wrote for an API process he’s been working on, I can jump right in because, as I’ve said, Markdown (even in its raw form) can be read by anyone. It puts the engineer and myself on the same page, and it keeps us there together. Plus, most Integrated Development Environments (IDEs) feature text edit areas where Markdown acts as the default markup language for writing.

So, from a technical writer’s perspective, Markdown is a writing tool that keeps documentation formatting a breeze, but it also moves us technical writers closer to developers because it allows us to speak (and write) in the same language and use the same basic formatting syntax. And the best, most useful documentation is created when developers and technical writers are on the same page.

4: It’s collaborative

Markdown is more than just a simplified language. The power of Markdown is that it levels the playing field for technical writers and fosters collaboration between them and engineers—especially technical writers without deep, technical backgrounds.

A technical writing organization that sets Markdown as their default markup language for all documentation opens the door for more technical writers to be hired from diverse backgrounds. This is because one can upskill into being proficient with Markdown quite quickly, as opposed to XML and HTML. I like to call it the great equalizer. Documentation, in many ways, is the unsung hero of every product and engineering org. And in the end, it all comes back to Markdown.

Where to go from here

I’ve long been interested in programming, and I’ve learned a lot of programming skills in my free time. But when I knew I wanted to pivot to technical writing, the first thing I learned (and doubled down on) was Markdown. Before I started my career in this field, every engineer and technical writer I talked to recommended it as, literally, one of the first things I should learn. So I did—and I’m so glad!

Now, as I’m sure those who work closely with me know, I evangelize Markdown whenever I’m given the chance—with colleagues, with folks who come to me wanting to transition to technical writing, and with clients. In my eyes, Markdown is the backbone of modern technical writing and documentation, and it isn’t going anywhere. It is the soft standard for documentation in the world of tech and, eventually, I believe it will just be the standard across the board.

Markdown is the future of technical documentation. And as more and more companies, IDEs, and coding repositories use it as the default markup format for editing and writing documentation, that future is starting now. If you’re starting to write documentation or are considering technical writing, I highly recommend learning Markdown. It will serve you well.

The post Four Key Reasons to Learn Markdown appeared first on Big Nerd Ranch.