Do Agile Technical Documentation using Markdown

-

    Drive down costs and increase productivity is the theme for running a business in our current times. Quite often, documentation in a company is a monolith that is expensive to maintain, and fixes to it may not address the long-term problem. It is challenging to make information more accessible. This document describes documentation ideas that can apply for a startup or any company which follows Agile methodology. The idea is to keep the costs low, develop the documentation incrementally, and make it work for the long term.

Some of the tools that we use can make our work more simple or more complex. All information must be captured in real-time and must be curated well. Hosting the information online will make it available to the stakeholders in real-time. Also, the company must be careful about not getting locked into a few tools which can drain money and resources.

Try the following ideas: Use Markdown to create portable content and host the contents online using a Static Content Generator. Using Markdown will help developers contribute to Technical Writing.

  • Use Markdown
  • Use a Static Site Generator

Use Markdown

Typora Markdown Editor

Typora is a GitHub Flavored Markdown(GFM)[1] editor. It has many additional features and allows export to HTML, PDF, and other formats.

Install Typora and Pandoc

Typora requires Pandoc for some of its advanced features.

Typora
Pandoc

Typora training links

Quick tips for using Typora

  • Select Paragraph from the tool menu to apply paragraph styles.
  • Select Formatting from the tool menu to apply formatting such as bold and italics.
  • Select Paragraph > Table > Insert Table or Ctrl+T to insert a table.
  • Insert Format > Image > Insert Image or Ctrl+Shift+I to insert an image. The Zoom Image setting helps render the image with the correct size.
  • Apply your preferred CSS stylesheet by selecting a theme from the Themes menu.
  • Navigate to Help > Custom Themes to use a custom theme and refer to other help topics:
  • Apply links, see https://support.typora.io/Links/

Sample cross-reference:

[What is Markdown?](###What-is-Markdown?)

What is Markdown?

Sample hyperlink:

www.security.honeywell.com

Default hyperlink:

[www.security.honeywell.com](www.security.honeywell.com)

Edit the hyperlink as required:

[www.security.honeywell.com](https://www.security.honeywell.com/)

Note: The text placed inside the Code Fences (Paragraph > Code Fences or Ctrl+Shift+K) is not parsed by the markup.

  • Apply Footnotes:

You can create footnotes like this[^fn1] and this[^fn2].

[^fn1]: Here is the *text* of the first **footnote**.
[^fn2]: Here is the *text* of the second **footnote**.

  • Apply TOC, select Paragraph > Table of Contents.
  • Select File > Export for the export options. You have a number of options including HTML and PDF.
  • Apply Preferences settings:
  • Select File > Preferences > Markdown. The options available here enables you to use subscript, superscript, highlighting, and other options in the text.
  • To enable autosave, select File > Preferences > General and select the Auto Save option.

Pagebreak is among the very few instances in which I use native HTML tags. You may need the page break option to move some contents to the next page in the PDF output.

<P style="page-break-before: always">

What is Markdown?

Markdown is a plain text format for writing structured documents, based on conventions for indicating formatting in email and usenet posts. It was developed by John Gruber (with help from Aaron Swartz) and released in 2004 in the form of a syntax description and a Perl script (Markdown.pl) for converting Markdown to HTML. In the next decade, dozens of implementations were developed in many languages. Some extended the original Markdown syntax with conventions for footnotes, tables, and other document elements. Some allowed Markdown documents to be rendered in formats other than HTML. Websites like Reddit, StackOverflow, and GitHub had millions of people using Markdown. And Markdown started to be used beyond the web, to author books, articles, slide shows, letters, and lecture notes.

What distinguishes Markdown from many other lightweight markup syntaxes, which are often easier to write, is its readability. As Gruber writes:

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. (http://daringfireball.net/projects/markdown/)

Why Use Markdown?

You might be wondering why people use Markdown instead of a WYSIWYG editor. Why write with Markdown when you can press buttons in an interface to format your text? As it turns out, there are a couple different reasons why people use Markdown instead of WYSIWYG editors.

  • Markdown can be used for everything. People use it to create websites, documents, notes, books, presentations, email messages, and technical documentation.
    • Markdown is portable. Files containing Markdown-formatted text can be opened using virtually any application. If you decide you don’t like the Markdown application you’re currently using, you can import your Markdown files into another Markdown application. That’s in stark contrast to word processing applications like Microsoft Word that lock your content into a proprietary file format.
  • Markdown is platform-independent. You can create Markdown-formatted text on any device running any operating system.
  • Markdown is future-proof. Even if the application you’re using stops working at some point in the future, you’ll still be able to read your Markdown-formatted text using a text editing application. This is an important consideration when it comes to books, university theses, and other milestone documents that need to be preserved indefinitely.
  • Markdown is everywhere. Websites like Reddit and GitHub support Markdown and lots of desktop and web-based applications support it.

Alternatives to Markdown

You can create API Guides and other guides using tools such as Confluence wiki, AsciiDoc, and Swagger still without the need for proprietary authoring tools:

Use a Static Site Generator

Markup integrated with a Static Site Generator is the perfect way to host content online. Static Site Generator can be a better alternative to traditional CMS such as WordPress. It is easier to implement and delivers content fast as it does not need to pull anything from the database. There are several open-source and free Static Site Generators, which helps keep the overall cost very low. Host the markup content online using a static site generator such as GitBook, Docusaurus, Hugo.

It is quite easy to install and set up a Static Site Generator. Check out the steps for installing Docusaurus at https://docusaurus.io/docs/installation

Other resources:

The ability to learn is the key to survival. We can learn faster by learning from each other.

[1] GitHub Flavored Markdown, often shortened as GFM, is the dialect of Markdown that is currently supported for user content on GitHub.com and GitHub Enterprise.

Comments

Post a Comment

Popular posts from this blog

Insert images in Typora

-
Image
     I started toying with the idea of using Markdown for documentation only a couple of months ago and happened to pick Typora as my choice of Markdown Editor. You can tutor this tool by yourself in a single day, but it takes time to learn some nuances if you are learning it all by yourself. For a long time, I thought Typora doesn't have the option to add a cover page, header, footer, and page numbers, and last week I figured out that we can do all these by using the YAMAL front matter. You can add typora-root-url to the YAMAL front matter to insert images by their relative path. To know more, see: https://support.typora.io/YAML/ https://support.typora.io/Images/ Related articles: YAMAL front matter in Typora Use markdown for your README Why I am gung-ho about Typora Conditional text in markdown Author documents using markdown Using mermaid in markdown Do agile technical documentation using markdown Tool independent technical documentation Techniques for cost-effective ...
Read more

Apply Goldilocks principle

-
Image
     There is one thing universal about successful managers. They keep increasing the performance benchmark every time. It applies to an athletic coach who wants to make his trainee globally competitive. I have worked under cruelly kind managers who are very ruthless in getting the tasks done. They push you to improve your competency and skills every day. You may have had a tough time working under this manager, and still, it is not something to be resented. Weathers the pressures work? We start looking for ways to do things better when the competitive edge is so narrow, and even a marginal improvement in something will give you an edge over your competitors. I had my dilemmas over if harsh managers are good or bad. A good manager sets difficult but attainable benchmarks and allows members to execute tasks with relative autonomy. There is no use flogging a dead horse. Spend time grooming the people who are motivated to do their best. I have spent time with people who do n...
Read more

Technical Writing essentials

-
Image
     I want to share some of my learnings starting from the beginning days of my Technical Writing career. Everyone in the project must have a cursory understanding of the following, and the Technical Writer must understand it in detail: Language standards Learn the style guides. MSTP (Microsoft Manual of Style - currently called Microsoft Style Guide) is among the most widely followed style guides. You can access it online for free and even download the PDF for offline reference. See https://docs.microsoft.com/en-us/style-guide/welcome/ There are several other style guides, but it is mostly enough to refer only to Microsoft Style Guide. The following are some of the key takeaways: Avoid passive voice - sentences in passive voice are generally longer and harder to read. Use only the simple and easy words understood by the global audience with varying degrees of English knowledge. Your writing must have the same meaning for all people from different geographies and culture...
Read more