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 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:
✖ …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.