Writing Tools

Purpose

I built two websites for my technical writing samples because I use two types of markup languages: Markdown and reStructuredText. The markup code syntax varies and each has its capabilities and limitations. The purpose is to show that I can perform the essential functions of a technical writer:

  • Write concise documentation that helps the reader solve a problem.
  • Structure documents to present information in a logical order.
  • Use a markup language to create effective documentation in a readable format.
  • Maintain version control repositories for source code.

Writing Tools

I prefer to use a text editor to write documentation and use services such as WordPress, Git and GitHub, and Read the Docs to manage and host my writing samples.

Application Function
Microsoft Visual Studio Code Markup text editor and code editor
WordPress.com Website hosting service
Git Command line tool to manage repositories
GitHub GitHub repository for version control
Read the Docs Documentation hosting service

WordPress Blog Posts and Writing Samples

On WordPress, I use Markdown to write samples that are posted on my blog. WordPress converts the Markdown markup language to HTML. Markdown does not always have syntax for a feature that I want to use, such as admonitions. When that occurs I use HTML and CSS which is rendered by WordPress.

Markdown is not standardized but most versions support basic Markdown features such as formatting and links. Some of the common Markdown versions include the following, but there are other versions available on the Internet.

Application Function
Markdown on WordPress WordPress Markdown reference
PHP Markdown Extra Provides improved Markdown features on WordPress
HTML Tutorial w3schools.com HTML Tutorial
HTML Character Sets w3schools.com HTML character sets
HTML Color Tutorial w3schools.com HTML colors
CSS Tutorial w3schools.com CSS Tutorial
CommonMark Potential standard for the Markdown syntax
GitHub Flavored Markdown GitHub version of Markdown
DocFX Flavored Markdown Compatible with other versions of Markdown and adds features

reStructuredText Samples

My writing samples that are written with reStructuredText are developed with the Sphinx documentation generator, stored on GitHub, and hosted on Read the Docs. These tools are extensible and are a good option for technical documentation. These tools are based on Python, familiar to Python developers, and are used to create Python documentation.

Application Function
reStructuredText Markup language for technical documentation
Sphinx Documentation generator
Python Python Software Foundation