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.
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.
|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.
|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|
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.
|reStructuredText||Markup language for technical documentation|
|Python||Python Software Foundation|