Context

As an early-career engineer, I've noticed that many engineers dislike writing documentation. I'm curious about exploring ways to ease their reluctance to begin.

The simplest form of documentation is found in almost every version control repository - README file, i.e. Markdown document.

In my project context, documentation is often required to be converted to Word Document as well. That's where Pandoc can help with the conversion between different formats.

---

Markdown Resources

There's no fancy formatting is Markdown. Typical elements used includes but not limited to:

• Headings

• Styling - bold, italics

• Lists (Ordered/Unordered)

• Hyperlinks

• Images

• Tables

• Quoting codes

A good resource for reference would be [CommonMark's guide](https://commonmark.org/help/) and even has a [tutorial](https://commonmark.org/help/tutorial/) to get started!

---

Execution

I will be using sample.md for illustrating the conversion to Word Document sample.docx . The document contains the following elements

• Paragraphs of content (dummy text)

• Images

• Tables

Convert Markdown to Word Document

In the command below,

• --number-section : To include the numerical sections for each heading and sub-heading in incremental order

• -t docx+native_numbering : To indicate the target format, i.e. Word Document and work with the Word's native numbering system for its figures and headers

• --trace : To indicate the progress of converting the document

pandoc "sample.md" --number-section \
  -t docx+native_numbering -o sample.docx --trace

Diagramming

For drawing diagrams, I find Mermaid to be useful to draw diagrams using Markdown. Here's an example of a Mermaid flowchart:

```mermaid
flowchart LR
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]
```

You can try it out in the [Mermaid Live Editor](https://mermaid.live/)

---

Why this matters

Quoting from the book - "How to Take Smart Notes" by Sönke Ahrens,

Most people struggle for much more mundane reasons, and one is the myth of the blank page itself. If you believe that you have indeed nothing at hand to fill it, you have a very good reason to panic. Just having it all in your head is not enough, as getting it down on paper is the hard bit.

That is why good, productive writing is based on good note-taking. Getting something that is already written into another written piece is incomparably easier than assembling everything in your mind and trying to retrieve it from there.

Very often, engineers will collaborate with business analysts and/or technical writers to come up with the documentations required for project requirements. Preparation is key to successful writing, especially when collaborating with others. It's normal to struggle with writing documentations, yet it's crucial to start nonetheless.

Call for Action

With a simple Markdown document, I would like to urge engineers of all levels to start small by taking notes in point form regularly.

As I always say these pet phrases to my peers, I say it to you

• Please write it down!

• Point form over nothing!

---

Up Next

I will be doing more in-depth exploration for the customisation of the reference document and the caveats to look out for

Stay tuned, cheers! 🍻