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, white-papers
  • The documentation as code philosophy with Git version control
  • Lightweight markup—reStructuredText, AsciiDoc, Markdown, etc.
  • 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 detailed 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 complicated 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

I am familiar with a broad range of software-related topics, and particularly those that are associated with the free and open source software community. 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 overview of my experience and may or may not be relevant to your particular project.

  • 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, Docker, 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, Teredo, 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.