I feel like technical writers are kind of a difficult creature to understand. Documentation is one of those words that means so many different things to so many different people, but primarily, we build written resources that explain how to use technical products. In my career, the technical products have been software. The audience for my writing has been admins, developers, or non-technical end-users. There are a number of ways to do this, ranging in appearance and complexity. Sometimes I work with documents in a way that looks like code or fiddle with template files for websites. Other times I work through a user interface designed for publishing to multiple endpoints. So I think it typically makes sense for technical writers to be flexible, understanding enough to work with different kinds of tools.
After all, we’re kind of generalists. We need to be able to understand how technical products work. And when you produce documentation, you should probably be pretty good at using documentation as well.
So, here’s a snapshot of my current setup. Maybe I’ll revisit this in five years! A quick caveat: if you prefer more user-friendly paid services, this DIY toolchain might not be your cup of tea!
Hardware
I use a Framework 13, equipped with an AMD Ryzen 7 CPU and Windows 11. It’s a pretty cool little laptop, but I wouldn’t recommend it for everyone. I’ll go into the pros and cons below. I’ve been debating dual-booting with Linux, but for app compatibility and ease of use reasons, I’ve stuck with Windows. When I need to use a Linux development environment, WSL2 is there. But more about that in my software section.
Over the years, I’ve used various laptops: MacBooks, Asus netbooks, and more. I enjoy exploring different operating systems and hardware, configuring tools to meet my needs. I’m someone who likes to fiddle with hardware and switch between environments. So what works for me might not work for you!
Pros
I love the Framework’s modularity with swappable expansion cards (HDMI on the left instead of the right? No problem!), privacy sliders for the microphone and webcam, and Linux support. I’m debating returning to desktop Linux depending on how Windows evolves. The matte screen is a bonus for productivity, reducing glare and has an excellent resolution. It is honestly pretty comfortable for blogging with Hugo running in server mode (for my editing flow) or comparing diffs in VS Code.
Battery life and CPU are perfect for what I need. It’s not spooky-great like Apple’s silicon, but the AMD Framework meets my needs for a day on the go.
What really draws me to it is that every component on the laptop can be upgraded or swapped out for repairs. If I find that media processing or development tasks require more memory than I have, I can order compatible sticks and do the upgrade myself. If the screen is damaged? That can be replaced.
While the ability to repair is dependent on the continued operation of the company, this is so radically different from every other laptop manufacturer that I think it’s worth supporting. This has been successful enough that Intel seems to be jumping on the bandwagon!
Cons
The modular IO ports can be finicky with the AMD mainboard. Where I put the USB-C and HDMI modules matter with the AMD mainboard. It doesn’t break my experience, but you do have to think about things.
The keyboard and trackpad are also misses for me. The keyboard is functional, but it’s not as good as the Macbook style scissor switches. There’s noticeable flex when typing. I also don’t love that f12 is mapped to launch the Framework marketplace by default (cat stomps can suddenly open a browser window). The trackpad isn’t on the same level as Macbook’s for gestures. But honestly, I use mine with a mouse more than the trackpad.
The build quality is a little middling - It’s not bad, but it’s not as sturdy or well put together as some of the alternatives in the price range. The hinges are a bit too easy to open, and bouncy train rides can be an issue.
I have noticed that in my current workflows, the 16GB of ram I configured it with isn’t quite enough. Having multiple apps open (Discord, Slack, VS Code, Front… etc.), and then trying to work with WSL2 gets a little dicey. Thankfully I can upgrade! But for building this site or other lightweight platforms, this machine works wonderfully.
Peripherals
A couple of other essential things:
- An external monitor, I have a 32" 1440p display
- A mechanical keyboard (I alternate between a Keychron K6 and a Keychron C3 Pro)
- Logitech MX Anywhere mouse (for portability)
- Steelseries over-ear headphones for long focus sessions or calls
- A USB-C to HDMI, USB-C, and USB adapter
- Leuchtturm 1917 notebook
- Lamy Al Star loaded with black ink
Software
A software technical writer is responsible for producing written content to explain how software works. This is usually in the form of a help center or docs website. In other branches of technical writing, you may produce print or PDF manuals. I work with static site generators (SSGs), content management systems (CMSes), and learning management systems (LMSes) to produce and host content to explain how software works (including videos and screenshots). I think the choice of docs system really depends on how you envision your team functioning and who contributes to your documentation.
There are strong reasons to prefer docs-as-code as a methodology (using Git, SSGs, workflow automations, and tests) if you have a community of contributors who are comfortable with Git and markup languages. There are strong reasons to prefer a CMS if you have a community of users who are more comfortable working in what-you-see-is-what-you-get (WYSIWYG) type environments. While specialization and tool knowledge is valuable, it can pay to be a bit of a generalist.
For this site, I rely on Hugo, which is a static site generator, and a common tool for docs-as-code projects. Version control, revisions, and experimentation are all easy to handle using Git and Github. I write inside of VS Code, making use of extensions to handle spellcheck and syntax highlighting. It’s also easy to extend and support your docs-as-code projects with helper scripts and functions to carry out automations.
I run Vale, a linter (tool to check each blog post against a set of style rules), a python script to check links, and python script to move images to a folder I back up to Google Drive (saving me from backing up image files in Github). In my contract work, I can use this setup to build and test templates and configurations for CMSes and LMSes using Docker containers. This involves working a bit with Windows Subsystem for Linux (WSL), which has been a great way to have a flexible and customizable development environment in addition to the more stable Windows environment. Running WSL, Windows, and various productivity apps is where I feel the ram pinch a bit, but taking a bit of care to ensure I’ve properly configured the Docker and WSL has made things workable (along with minimizing the number of other apps I have open while I’m focussed on these tasks).
Here’s a summary of ones that I find particularly useful with an emphasis on free or open source options:
| Category | Tool(s) | Notes |
|---|---|---|
| Operating System | Windows 11, WSL2 | I chose this for its battery life and software compatibility. WSL2 allows access to a Linux environment if needed (e.g., with Docker) |
| Productivity & Utils | PowerToys (FancyZones, PowerRename, etc.) | This is essential for a Windows 11 user. Various handy utilities, worth it alone for bulk renaming of files. |
| Development | VS Code, Git, GitHub Desktop, Hugo, Pa11y, Vale, PowerShell, Python | VS Code is my primary code editor; Git and GitHub manage version control; Hugo is used for static site generation; Pa11y and Vale automate accessibility and style checks; PowerShell is the primary terminal. |
| Screenshots | ShareX | A powerful and configurable screenshot tool. |
| Video | OBS Studio, Kdenlive | OBS Studio is used for screen recording and streaming; Kdenlive is used for video editing. |
| Audio | Audacity | Used for audio recording and editing. |
| Command Line | Chocolatey, ImageMagick, Pandoc, etc. | Chocolatey is a package manager; ImageMagick and Pandoc are used for image and document manipulation, respectively. |
| Browser | Chrome, Firefox, Edge | Multiple browsers are used for different workflows and testing. |
| Note-Taking | Obsidian | Used for its linking, search, and knowledge graph features, useful for drafting and managing content in various formats (Markdown easily transfers to Hugo projects, Google Docs). Joplin or Logseq is an alternative. |
I am purposefully leaving off an AI tool. There is a range of these available, and most of them will work well for general queries and editing, within reason. All of the major providers support adding materials and files as context. The important thing is that they aren’t essential for my kind of workflow and many of them are functionally interchangeable. If you are working as a contractor, it’s also important to meet requirements from the company you are contracting with, so keep in mind confidentiality and security.
Final thoughts
I think that this is a pretty powerful web-publishing tool set and you can work through this with fairly minimal licensing fees — Obsidian requires a license if you are using it for commercial purposes, but everything else (aside from Windows), is freely available. I also feel that I could adapt this toolchain to Desktop Linux or MacOS with fairly minimal changes, which means it’d be flexible enough for any company I’d be going to work with. The repairability of my laptop also means that I can keep it going in the event of a hardware malfunction, but so far the Framework has been stable and powerful.
It will be interesting to see how I feel about the Framework in five years, and whether I’ve done a modular upgrade. My last personal laptop was a Macbook Pro that I used for more than a decade. I’m feeling confident that this tool chain will work well into the future.