Services Provided

About my work

I provide technical writing and consulting services to clients requiring high quality, detailed software documentation.

  • User guides, reference manuals, technical articles

  • The documentation as code philosophy with Git version control

  • Lightweight markup—reStructuredText, AsciiDoc, Markdown (and related, such as CommonMark and MyST)

  • Output generation systems built with Pandoc, Asciidoctor, Sphinx, LaTeX/ConTeXt, etc.

  • Original research and testing for development of new documentation

  • Style guides, templates, training materials, policy documentation, and other resources for writing teams

Some more specific examples:

  • Diagrams with tools like Graphviz, PlantUML, and Asciidoctor Diagram

  • API/developer documentation with automatically generated content

  • Converting and importing pre-existing documentation in other formats

  • Docutils, reStructuredText; implementing custom roles and directives

  • Generating embeddable HTML for website integration

  • AsciiDoc, Asciidoctor, Asciidoctor PDF

  • Reporting issues and potential improvements to development teams

  • Bash/POSIX shell scripting, Python

  • Git, GitHub, GitLab

  • Creating e-books (EPUB, PDF)

  • Implementing documentation build tests and dependency checks

  • Integrating content from multiple repositories

  • Maintaining common generation scripting and resources across multiple projects

  • Maintaining publishing metadata in the documentation source

  • README files, Unix-style man (manual) pages

  • The various flavors of Markdown, including CommonMark

  • Image processing with GraphicsMagick or ImageMagick

  • Publishing content to/from both public and private repositories

  • Documenting obsoletion and deprecation of old functionality

  • LyX—a document processor based on LaTeX

  • Including dynamic content from databases

For examples of my work, please see the Portfolio page.

How I can help you

Quality documentation is vital for the success of a product, because it is directly related to the experience of the user. However, easy-to-read documentation is not easy to write, especially when it is describing a complex product or process.

Your documentation may:

I can:

✖ …not exist or not be comprehensive.

✔ …write new documentation or extend what you already have.

✖ …use a markup or structure that is difficult to maintain and prevents collaboration.

✔ …convert the documentation source and improve the generation system. This can offer advantages such as collaboration via GitHub, automated publishing, and maintaining variants of the documentation without duplicating content.

✖ …be fragmented; with multiple documents and various layouts, formats, and writing styles.

✔ …collate the documents, organize the content, remove any duplication, and edit to a consistent writing style.

✖ …have been written from the perspective of the developer, including unnecessary technical details and omitting points that would be helpful to the reader.

✔ …rewrite the documentation with consideration for the user’s perspective.

✖ …be incorrect, due to changes in the product as it has matured. For example, features may not work as the documentation indicates.

✔ …test your product and your documentation, fix errors in the documentation, and report usability or other issues to the development team.

There are many other ways that I have helped clients build excellent documentation. I would like to find out more about your project—please contact me.

Topics I have experience with

Here is a list of specific topics I have worked with and/or written about. Note that the items listed below are intended only to give a broad, general overview of my experience; this list is not comprehensive.

  • Operating systems: Debian GNU/Linux, CentOS Linux, Microsoft Windows and Windows Server, Apple macOS, Qubes OS, OpenWrt

  • Version control: Git, GitHub, GitLab

  • Programming/software: Bash, POSIX shell, Python, Ruby, regular expressions, data serialization (CSV, JSON, YAML), plain-text configuration systems

  • Web development: HTML, CSS, Django, standards compliance, responsive design, browser support, browser testing, Nginx

  • IT tools: Ansible automation, QEMU emulator

  • Security tools: Linux Audit system, SELinux, PGP/GPG signing and encryption

  • Log processing: parsing, filtering, forwarding, buffering, rsyslog, NXLog, Splunk, Snare, Elasticsearch, Kibana, many logging protocols and formats used by various systems and software

  • Double-entry accounting: GnuCash, Ledger, Beancount

  • Networking: IPv4, IPv6, dual-stack networks, DNS logging and security, iptables, nftables, iproute2 routing/traffic control

  • Professional sound systems

  • Vector graphics: Inkscape, Adobe Illustrator

  • Two-dimensional computer-aided design (CAD)—LibreCAD

Please contact me so we can discuss your project.