Markdown for Copywriting

As a data scientist, I spend most of my day working with SQL and Python using SQL Server Management Studio (SSMS) and Visual Studio. I know that a lot of time when I'm building my ML models and training and testing them, I'm not worried about the formatting and presentation of my work. 

However, as I've also been involved in marketing efforts for companies I've worked at, I found that sometimes you need to prioritize the final presentation for the general public.

Because of this, I've started working on markdown in VS code, using inline code, and exporting to a final PDF for presentation purposes.

Sometimes Looks do Matter

While I love using jupyter notebook - it's definitely my go-to platform for python coding - when it comes to presentation, I find it's not user-friendly. You need to install all the right packages to the right path with the right credentials to even export one jupyter notebook.

I'm not saying that you shouldn't go through the steps, but if you're working on a computer that might have specific admin credentials needed or software installed to block some of these packages, it might be easier just to use VS code and get an extension. 

I spent an hour today trying to get the right packages installed in the right paths with the right credentials to export my ipynb as a pdf and I was ready to scream. Instead, I stopped what I was doing and took a different approach.

I opened up my VS Code and created a markdown file...

The cool thing about markdown is you can write your text-based presentation and your code (SQL, Python, R, etc.) in one place. I find that this is most helpful when I’ve already finished my entire analysis and I’m just focusing on making everything look presentable. 

So yesterday, after I abandoned my jupyter notebook, I had my whole notebook rewritten in markdown with inline code for the Coding Style Guide I was creating for my team in less than 15 minutes.

Writing Markdown

If you’re unfamiliar with markdown, a good resource is MarkdownGuide.org. Their cheat sheet is basically a crash course in markdown, including the syntax for headings, bold, italics, lists, inline code, and more. 

If you want to see how markdown works, this demo on GitHub is pretty useful:

‍

Though it might seem overwhelming at first, markdown is incredibly useful, and not just for coding. For instance, some blogs and wikis are formatted with markdown and if you can create your own file then you’ll have more opportunities to customize your pages, whereas if you rely on a text-to-markdown converter you are bound by those limitations.

Markdown can also increase your efficiency as a writer. Instead of having to stop typing to highlight text and click on formatting options, you can essentially just type everything with the formatting built in. 

For example, rather than manually formatting my headings, I use different # symbols to represent heading levels. 

Using a Markdown Editor

One thing that’s important to note when writing markdown is that you’ll want a good markdown editor. Specifically for Windows, there are a few competitors out there that offer free and paid markdown editors that can make your life a lot easier. 

Personally, I rely on VS code for my markdown and Notepad++. They’re both free to use and have extra plugins/add-ons to make your life easier when writing, coding, and presenting.

Technical Copywriting with Markdown

If you’re a technical writer, learning how to write in markdown is important. By doing so, you can set yourself up for success in terms of new opportunities for customizing text and presentations. 

But what if you don’t feel confident in your own technical writing abilities? No problem – just contact us today to get partnered with a technical writer who is skilled in writing, coding, and markdown to take your brand’s message to the next level.

‍