How to gain technical writing experience

Technical and professional writing is an active and growing field. Organizations still need real people who can write well, and are always on the lookout for skilled technical and professional writers. Some are graduating students who look to technical writing as a career option, others are entering from another career area and want to transition into technical writing.

As the senior editor at Technically We Write, I often get asked for advice about how to transition into technical writing. I wanted to share my recommendations in this article.

While most of my career has been focused in IT Leadership, I also enjoy technical and professional writing. That’s why I started Technically We Write and Coaching Buttons. I also have a long history in open source software, going back over thirty years with the FreeDOS Project, and I like to write about open source software. So many of my recommendations will be connected to open source software in some way. But you can apply this advice when writing for other kinds of websites.

Writing about open source software

One “first contribution” avenue I recommend is writing about open source software, then go on from there to write for open source projects. But that’s my perspective as someone who writes a lot of articles about open source software.

If you’re looking to earn writing experience, writing about open source software is a great place to start. I can recommend several places to write about open source software:

We ♥ Open Source launched several months ago as a community website, sponsored by the All Things Open conference. I’ve written several articles for them, and I plan to write more. All Things Open aims to publish all kinds of articles about open source software - so if you write an article with an open source connection, they are likely to accept it. For example, you might write an article about “how to create a business card in Scribus” or “how to make a poster in Scribus” or “how to format a printed document in LibreOffice Writer” or “how to use Styles in LibreOffice Writer.” All Things Open: We ♥ Open Source would welcome “how-to” articles like that.

Both.org runs articles about all kinds of open source software. The website started as a personal blog by David Both - author of several Linux books - but he opened it up as a community website about open source software. Based on articles that have been popular there, the readers are probably more technical. That means you could write an article like “how to create a website in HTML” or “how to use CSS stylesheets with HTML” or “how to write your first Markdown document” or “getting started with XML.” Articles like these will be very popular on Both.org.

This website, Technically We Write, is about all kinds of professional and technical communication. We welcome articles about technical and professional writing, including advice, tips, tricks, tools, and tech. For example, you could write an article like “what is a technical description” or “what is a layout grid” or “how to write a set of instructions” or “how to format an IMRaD research paper.” We have a pretty wide audience at Technically We Write, so you could also write an article about your favorite keyboard, or your favorite editor, or your favorite word processor. Those are all great topics that our readers want to know about.

Fedora Magazine runs articles about Fedora Linux. I’ve written several articles for them, and as long as your article is about Fedora Linux, they’ll likely run it. For example, you could download the Fedora Linux image for Fedora Workstation, write it to a USB flash drive, then boot your PC with it. You don’t have to install Fedora; it can run as a “live” image, so you can just use it without installing it to your computer. Experiment with the live system, then write an article like “my first impressions about Fedora Linux” or “3 things I liked about Fedoras a first-time user” or “4 things I taught myself how to do in Fedora over a weekend.” Those are excellent topics that they would probably be interested in. Fedora Magazine has a web page to pitch an article or to become a writer. They also welcome volunteer editors; check out their web page to become an editor.

Linux Journal is the oldest Linux magazine around. I used to write a lot of articles for them before they “closed” - but were then rescued by Slashdot Media. I had an email discussion with the editor last year, and he welcomes new article contributions. They tend to run articles about “Linux” topics, although many of their articles are more technical in nature. But if you installed a Linux distribution, such as Fedora, on a virtual machine and experimented with it, you could write an article for them about “4 things I liked about using Linux for the first time” or “5 tips when trying Linux for the first time.”

Writing for open source projects

Many new contributors to open source software projects hesitate because they don’t consider themselves very “technical.” They fear they won’t be welcomed because they don’t know how to write program code; they “only” know about technical writing. I have to tell you: most open source projects would love for someone to help with technical writing.

What you have to remember about most open source software projects is that writing the code is the thing they find most interesting. Writing the documentation is secondary. It’s not that open source projects don’t value good documentation - they just aren’t focused on it. For open source projects, documentation is something they have to write, rather than something they want to write.

And in my experience, most open source developers would be thrilled if someone emailed them with this:

“Hi, I’m __ and I like using __. I’m a technical writing student, and I’d like to help with your documentation. Is there something I can do to help?”

It helps to have a connection to the open source project in some way, like if you use it already. But you don’t have to use it to contribute to the documentation. For example, I know a lot of open source developers who would be happy to get an email like this:

“Hi, I’m a technical writing student, getting ready to graduate from __. I love tech writing, and I’d like to help with open source documentation. Is there something I can help with? For example, I could update documentation for grammar and plain language. I am most familiar with HTML and Markdown.”

Larger, more established open source projects like GNOME, Firefox, Fedora, Virtualbox, and Chromium likely have a formal documentation team, and they are usually very welcoming to new contributors. Email them and ask!

Smaller open source projects like Xfce or Pandoc or groff are usually just a few developers, and would be very interested to hear from someone who wants to write documentation. If someone came to them and said “I have experience in tech writing, and I’d like to update or write your documentation,” they would be happy to have you!

For example, I wrote the Toy CPU emulator, and the Readme is just something I wrote quickly based on a conference talk I gave about the Toy. The documentation should be completely rewritten, and include screenshots so users understand what to do.

I am part of the FreeDOS Project, and we are starting an effort to restart our “documentation project,” written in Markdown, hosted on a shared GitLab project. If you want to get involved by writing “how-to” guides, or “what-is” topics, you are welcome to join!

Also, our FreeDOS Help maintainer would appreciate help. Wilhelm has been the maintainer of the Help system for several years, with some assistance in writing and translating - but mostly it’s just been Wilhelm. The Help documentation is written in HTML, formatted using <pre> blocks because of historical limitations with the FreeDOS HTML Help viewer.

It’s easy to get started

You can find many “avenues” to get started in technical and professional writing. I’ve found open source to be a great first contribution, and an area where there is definite need.

In general, my advice for writing articles and documentation for open source is keep it informal and don’t write an academic paper. Pretend you’re explaining the topic to a good friend. A good way to structure an article is to start with two brief paragraphs that set the stage then jump right into the article topic. Use section headings to break up the topic into manageable “chunks” so it is easier to read. And include screenshots where they will help the reader to understand what is going on.