Product Tip: Markdown
Product Documentation with Markdown
Product documentation can be as simple as a README.md file in the repository (which most of us are familiar with, this in most cases is automatically generated when we create a repo), a wiki page or can be as complex as an entire sub-domain designed to fit the said product, as seen on most API docs , eg postman docs .
Documenting software is key. Product documentation is used in explaining to users and developers how the product operates, more like a self service scheme to getting started with using the product.
Markdown is a lightweight markup language with plain text formatting syntax. It is designed so that it can be converted to HTML and many other formats.Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid HTML. Mostly used by web writers.Markdown from it's initial goal was two things:
1) a plain text formatting syntax
2) a software tool, written in Perl, that converts the plain text formatting to HTML. Now it has been re-implemented in a number of languages, and with a number of additions.To format text,it uses punctuation and characters that most users are familiar with.
Developer: John Gruber
Release: March 19, 2004 (13 years ago )
Markdown is a minimalist writing style that you can use to get your text down and not worry much about it’s appearance, even when exporting to different platforms. Also it’s great when collaborating in writing and having to maintain a uniform style and pattern. This is because it’s a unified writing format.
In simple steps and in very minimal time, this is how to get started using the markdown for all your documentation:
Disclaimer, the output may break on different platforms because they support different markdown flavors. Copy the block below to dillinger and play around:-)
Headers# Tessie## Tessie## Tessie#### Let's keep testing this mardown thing##### Tessie###### TessieItalic*This is for italic stuff*Bold**This is for bold stuff**Strikethrough~~I have been striked through~~Linksthis is a link to my profile [Tessie](tessiewaithira.github.io)Imagethis is an image of my github profile Code and syntax highlighting:`tessie`Blocks of code```tessie is a star:-)```TablesTessie | Waithira|--- | --- |Tessie is | a star || Tessie is | a star |Blockquotes> Tessie is a starHorizontal linesTessie---or Tessie***or Tessie___Line breakVideos:[](https://www.youtube.com/watch?v=tQjsAJhsSw8)Issue reference#bugIDMentions@tessieLists- Tessie* Tessie1. TessieTask lists- [ ] Tessie task- [X] Mark as done- [ ] Waithira taskEmoji:blush:
Pros:
Clean outlook
Markdown formatted documents are clean and have no compex tags and formatting.
Commonly used
Markdown is the most universal lightweight markup language on the internet. It is great for a subset of tasks,ranging from blogging, emailing to technical writing and product documentation.
Cons:
Markdown seems a little complicated at first because the assumption is that it’s technical.This has been so because mainly the technical people have adopted it in their day to day writing. For a long time I shyed away thinking it was complex to write in markdown.
Markdown flavors which could also be a good thing for those who seek variety.There is no clearly defined Markdown standard, apart from the original write up and implementation by John Gruber. This has led to rise of different flavors as different people write their own variants of the language to create additions.
I think people should learn how to write in markdown at a young age, when they are being introduced to anything digital. It is beyond doubt an essential tool in a world that is gradually transitioning from paper to digital forms of information capture and storage.
From writing README, to pull requests to even documenting the entire product, Markdown has you covered. A useful tool for everyone involved in web writing, and an easy habit to pick up. Begin using Markdown today, and you will be happy you started:-)
Resources to get you started:
Dropbox Paper gives you a nice interface to write in and you can easily save the output to Markdown once you are done. What cool tools are you using for your online documents?
