Showcasing your API technical writer portfolio and projects — guest post by Peter Gustafson
- Portfolio Focus
- Portfolio Access
- Avoid Tech-Heavy Layouts
- Average Visitor Duration
- Portfolio Content
- Portfolio Color
- Got None?
- Docs-as-Code
- Join the Team
- About Peter Gustafson
My friend, Tom Johnson, is the granddaddy of API documentation. I ought to know since I’ve been stealing his stuff since 2012.
Back then, I was making the leap from marketing writer to API tech writer. But I had a menacing problem. I was clueless how to land my first job as an API doc writer. It took me a few years to land my first API tech writer role.
This article chronicles my journey building and upgrading my writing portfolio. Then covers some trends I see in the marketplace for technical writers.
Portfolio Focus
My portfolio focuses on the following attributes:
- Proves I’m not some crackpot desperate for a job.
- Demonstrates my experience as a proven tech writer.
- Provides readers easy access to my writing examples.
- Builds credibility by using a small dose of namedropping.
- Confirms I’m an expert in the API doc writing bonanza.
Recently, Tom and I were messaging on LinkedIn.com. He asked if I would write this article. I replied YES (duh). Getting published on Tom’s website is something I consider to be an honor. What follows are tips and tricks I’ve used to build a game-changing hiring machine portfolio.
Portfolio Access
Knock, knock. Who’s there? Your recruiter wondering… My recruiter wondering about what? Your recruiter wondering what the f#%k? How do I access your portfolio writing samples?
Remember, if your recruiter can’t access 100% of your writing examples in 3 seconds, fuhgeddaboudit. You won’t get interviews.
Huh?
Here’s the juicy portfolio access tip: it needs to be published online. If you’re churning out writing examples in PDFs, your chances of getting an interview are deader than disco. Seriously, some companies consider PDF writing samples as prehistoric.
Think about it from their perspective. Hiring teams review hundreds of applicants for just one job. So by forcing them to slog through your PDF writing examples, you reduce your chances of moving to the next round.
Thus, having an online portfolio is a must. Next, think about accessibility of your portfolio.
- My suggestion is to publish it online.
- Mine is powered by Wordpress.
- I built the site when I was doing SEO years ago.
- Then I trashed hundreds of SEO blog posts and retooled.
- Here’s my portfolio: https://www.pdgseo.com/portfolio.
There’s tons of site generators out there to build an online portfolio.
- I recommend GitHub pages & Jekyll.
- Wordpress is an easy one.
- Squarespace offers a nice CMS.
- Pick one and get good at building with it.
- Then upgrade your portfolio at least once a week.
Avoid Tech-Heavy Layouts
I ran into a UK-based tech writer recently on LinkedIn. She has an awesome portfolio built with github.io. Then powered by Docusaurus. The thing is a beast and reminds me of an API doc UI. She also has a beefy sidebar that links to each writing sample.
One night at about 2am when I was working on my portfolio, she pinged me. “What do you think,” she asked me about hers. Honestly, I thought it was far too confusing. I suggested she think about how recruiters would navigate her sidebar links.
My point is keep your portfolio simple. Portfolios sell your stuff. Then get you interviews. Mine isn’t the best in the world but it sure gets me tons-o-interviews. End of story.
You’re selling yourself with your portfolio. So try to avoid teched-out page layouts. Keep things clean and simple. With my portfolio projects, I have 4-8 sentences that describe the intended deliverables I managed for each company. Then I include links to the raw Markdown files and published articles.
Always ask yourself: can my recruiter evaluate my portfolio in three minutes or less? Yes? Groovy. No? Time to rework it and declutter the layout.
Average Visitor Duration
How long do you think hiring teams review your portfolio? Do you know?
Based on my portfolio analytics, it’s about 36 seconds. I know, it’s not long. Especially since I have 40+ writing samples of work I did for 12 companies. My point is that based on my analytics, hiring teams scan my portfolio, read a quick piece of content or two, then leave.
I view the topic of using website analytics as nice to know data points. That’s it. I’m not selling hotdog stands or products. So the reason I look at my analytics from time-to-time is to confirm people are spending some time on my portfolio.
What measuring stick do I use to prove my portfolio is making the cut? Interviews and job offers. Those are the only two data points that matter to me.
Portfolio Content
Way back in the day, I worked for a national advertising agency. I wrote between 25-50 radio and TV scripts a month. Sometimes more. We had a huge client list. So my DNA consists of large doses of marketing which I still use in my API doc writing.
As far as portfolio content, I recommend including the following:
An introduction at the top of what types of technical writing you specialize. For me, it’s 100% API doc writing. I also include a link to a contact form in the introduction.
I also include big logos of each company project I worked on which appear on the left column. On the right column, I include 4-8 sentences describing the project. Then I add the article title links (published and the raw Markdown file).
Portfolio Color
As you can see, I chose a black background for my portfolio page. I feel it adds better contrast for reading. We all stare at white screens all day so why not give busy reading eyes a break right?
Since my portfolio is powered by my Wordpress CMS, I have been using the Divi theme by Elegant Themes. You can do a lot of customization with page color inside the page widget.
Got None?
It can feel gloomy not having a well-structured portfolio. But what’s worse is having no work history to populate your portfolio. If you’re stuck with zero job projects to add to your portfolio, please understand I was once there myself. Ouch, it stinks. But there is a solution I used back in the day.
If you’ve got none, and are ready to build your first real portfolio, here’s what I recommend:
- Start by finding published SaaS articles online.
- Find ones that are clunky and confusing.
- Then rewrite each one.
- Pretty simple huh? Exactly.
I used this format back when I was moving into API tech writing around 2012-ish. I had no portfolio. So I started rewriting a lot of Amazon Cloud docs. Then I moved on to rewriting Stripe API reference docs. It takes time and focus but the benefits are enormous if you devote one hour a day.
Once you start building your portfolio with your new rewrites, include descriptions how you updated the content and why. Doing so forces you to evaluate published docs and pinpoint gaps in the content.
Another route is even easier…
- Work free for a SaaS project.
- Search Google for ‘Crowd doing’ and signup.
- Another great resource is to pilfer through StackOverflow for volunteer projects.
The volunteer route takes time and may be difficult to land something depending on your access to decision-makers.
Docs-as-Code
Skilled technical writers craft help content using the docs-as-code workflow via Markdown. If you’re new to API tech writing, consider learning to write in Markdown. It’s simple and with a little time, you’ll become a pro.
A tool I’ve been using for years (including writing this article) is Stackedit.io. It’s an online Markdown editor offering an easy user interface to write in Markdown.
Not all shops support docs-as-code. But any API tech gig I’ve landed in the last five years sure does.
I’ve worked with many technical writers who despise docs-as-code. Hmmm … I’ve always thought. You work with software engineers. Why not work like them?
When is docs-as-code dead wrong? Usually when you’re limited by the technology stack of your employer. In these cases I resort to writing in Confluence. One of the first questions I ask in my interviews is, “How are you publishing content?” Sometimes they have no clue. But it’s a good question and one that will keep you in the plus column for interview performance.
Docs-as-code is the best choice when managing API docs. I’ve worked on dozens of API doc writing contracts. More than a few were built by well-intentioned developers. However, I was brought in to simplify API docs by testing each endpoint. Then rewrite docs to include easy code examples and use cases.
Join the Team
Being embedded with software engineers is a must for API doc projects. Attending stand-ups and maintaining open dialogues with devs is the secret to writing easy-to-read API documentation. Endpoint testing is critical to understanding how to help new users onboard quickly to start pinging APIs.
Hopefully this article helps you sort out some of the common pitfalls working with your portfolio. I wish you the very best in your pursuits.
-Peter Gustafson
About Peter Gustafson
Peter Gustafson is an accomplished technical writer who started his technical writing business back in 2007, while being a stay-at-home dad. He juggled client calls and diaper changes during those early days. Before his technical writing career, Peter worked as a senior account executive in national radio and TV advertising from 1999 to 2007. Currently, Peter consults for blockchain companies and FinTechs looking to upgrade their API documentation. When he’s not working, he enjoys spending time with his kids, reading, volunteering, and continuously striving for self-improvement. To see samples of his work, visit his writing portfolio at pdgseo.com/portfolio. You can also follow Peter on Linkedin.