✍️ Markdown for Technical Writing
When you're starting off in technical writing for software, you might wonder what skills you all need. Do you need to learn a programming language, handle Git, or know markup? In this post, we'll look at Markdown and if/where it might be helpful for technical writers. Markdown or no Markdown? With 9 years in technical writing, I have to admit it's pretty surprising how far you can get without knowing too much about the technical background of software engineering. Especially if you're focused on end-user documentation for admins. So, is Markdown useful at all for technical writers? Markdown is useless for technical writers I'd disagree (therefore, it's a strike-through). But then, where does it come in handy? API Documentation If you provide API documentation for smaller open-source projects, it's likely that they use a README.md file to provide the documentation. Knowing Markdown will certainly help you prove that you're up to the task. Blogging as a Technical Writer Many technical writers started off as plain writers, meaning writing blog posts. Not all blogs require markup, but especially in the software world, blogging in tools relevant to the industry - such as GitHub and Co. - use Markdown. Providing your portfolio in Github can give you an extra edge when it's time to apply for a job as a technical writer in the software industry. How to Learn Markdown Now, all of the aforementioned sounds great and promising, but how do you go about learning Markdown? Let's dive into a structured plan for learning Markdown. Suggested Plan to Upskill on Markdown "I love it when a plan comes together." (John "Hannibal" Smith, the A-Team) Here's how I'd go about learning Markdown: Read online about Markdown. There are lots of great and clear overviews on the subject. Take a course about Markdown. Udemy, Coursera, and many other online learning platforms offer affordable courses. This will help you practice what you read about in step 1. Use Markdown to create your portfolio, or reference a post you created using Markdown. This will showcase your skill to your current (or soon-to-be new) employer. How much time should I set aside to study Markdown? Actually, Markdown is so simple that it usually doesn't take long to understand. If you look up a list of the basic syntax, you can be done in 15 minutes. If you want to practice it a bit while learning the syntax, 1 hour will be sufficient. Not too bad, right? I guess anybody has the time for such a short upskilling session. Examples for Markdown Here's an example of what Markdown syntax looks like while writing in a plain text editor: ### Suggested Plan to Upskill on Markdown > "I love it when a plan comes together." (John "Hannibal" Smith, the A-Team) ___ About Me Finally, some words about me and why I wrote this short post: I'm a technical writer for software products. Currently, I'm upskilling to get into programming, that's why I'm learning things like Markdown. And you might have guessed it - this post is part of a training. If you want to know more about this training, you can find it on Coursera. If any questions come up during the training, you can email the training instructor Dylan Israel at dylansemail310@gmail.com. If you want to know more about Markdown, check out this YouTube video: The Only Markdown Crash Course You Will Ever Need With that, we've reached the end of this post. Good luck
When you're starting off in technical writing for software, you might wonder what skills you all need. Do you need to learn a programming language, handle Git, or know markup? In this post, we'll look at Markdown and if/where it might be helpful for technical writers.
Markdown or no Markdown?
With 9 years in technical writing, I have to admit it's pretty surprising how far you can get without knowing too much about the technical background of software engineering. Especially if you're focused on end-user documentation for admins. So, is Markdown useful at all for technical writers?
Markdown is useless for technical writers
I'd disagree (therefore, it's a strike-through). But then, where does it come in handy?
API Documentation
If you provide API documentation for smaller open-source projects, it's likely that they use a README.md file to provide the documentation. Knowing Markdown will certainly help you prove that you're up to the task.
Blogging as a Technical Writer
Many technical writers started off as plain writers, meaning writing blog posts. Not all blogs require markup, but especially in the software world, blogging in tools relevant to the industry - such as GitHub and Co. - use Markdown. Providing your portfolio in Github can give you an extra edge when it's time to apply for a job as a technical writer in the software industry.
How to Learn Markdown
Now, all of the aforementioned sounds great and promising, but how do you go about learning Markdown? Let's dive into a structured plan for learning Markdown.
Suggested Plan to Upskill on Markdown
"I love it when a plan comes together." (John "Hannibal" Smith, the A-Team)
Here's how I'd go about learning Markdown:
- Read online about Markdown. There are lots of great and clear overviews on the subject.
- Take a course about Markdown. Udemy, Coursera, and many other online learning platforms offer affordable courses. This will help you practice what you read about in step 1.
- Use Markdown to create your portfolio, or reference a post you created using Markdown. This will showcase your skill to your current (or soon-to-be new) employer.
How much time should I set aside to study Markdown?
Actually, Markdown is so simple that it usually doesn't take long to understand. If you look up a list of the basic syntax, you can be done in 15 minutes. If you want to practice it a bit while learning the syntax, 1 hour will be sufficient.
Not too bad, right? I guess anybody has the time for such a short upskilling session.
Examples for Markdown
Here's an example of what Markdown syntax looks like while writing in a plain text editor:
### Suggested Plan to Upskill on Markdown
> "I love it when a plan comes together." (John "Hannibal" Smith, the A-Team)
___
About Me
Finally, some words about me and why I wrote this short post: I'm a technical writer for software products. Currently, I'm upskilling to get into programming, that's why I'm learning things like Markdown. And you might have guessed it - this post is part of a training.
If you want to know more about this training, you can find it on Coursera. If any questions come up during the training, you can email the training instructor Dylan Israel at dylansemail310@gmail.com.
If you want to know more about Markdown, check out this YouTube video: The Only Markdown Crash Course You Will Ever Need
With that, we've reached the end of this post. Good luck
