8.6 C
New York
Wednesday, March 13, 2024

Showcasing your API technical author portfolio and tasks — visitor submit by Peter Gustafson

by Peter Gustafson on Mar 12, 2024


How will you persuade potential employers about your API experience? One of many strongest strikes you may make is to share a hyperlink to your portfolio. The next is a visitor submit by Peter Gustafson, a technical author who’s had numerous success with API documentation tasks at many high-profile corporations. I used to be chatting with Peter on Linkedin the opposite week about tendencies he is seeing within the discipline, and I requested him to put in writing a visitor submit. On this submit, he explains the significance of getting a web-based portfolio that potential employers can simply entry and browse.

technical writer portfolio

My buddy, Tom Johnson, is the granddaddy of API documentation. I must know since I’ve been stealing his stuff since 2012.

Again then, I used to be making the leap from advertising and marketing author to API tech author. However I had a menacing downside. I used to be clueless how one can land my first job as an API doc author. It took me just a few years to land my first API tech author function.

This text chronicles my journey constructing and upgrading my writing portfolio. Then covers some tendencies I see within the market for technical writers.

Portfolio Focus

My portfolio focuses on the next attributes:

  • Proves I’m not some crackpot determined for a job.
  • Demonstrates my expertise as a confirmed tech author.
  • Supplies readers easy accessibility to my writing examples.
  • Builds credibility through the use of a small dose of namedropping.
  • Confirms I’m an skilled within the API doc writing bonanza.

Lately, Tom and I had been messaging on LinkedIn.com. He requested if I’d write this text. I replied YES (duh). Getting revealed on Tom’s web site is one thing I contemplate to be an honor. What follows are ideas and methods I’ve used to construct a game-changing hiring machine portfolio.

Portfolio Entry

Knock, knock.
Who’s there?
Your recruiter questioning…
My recruiter questioning about what?
Your recruiter questioning what the f#%okay? How do I entry your portfolio writing samples?

Keep in mind, in case your recruiter can’t entry 100% of your writing examples in 3 seconds, fuhgeddaboudit. You received’t get interviews.


Right here’s the juicy portfolio entry tip: it must be revealed on-line. Should you’re churning out writing examples in PDFs, your possibilities of getting an interview are deader than disco. Critically, some corporations contemplate PDF writing samples as prehistoric.

Give it some thought from their perspective. Hiring groups evaluate tons of of candidates for only one job. So by forcing them to slog via your PDF writing examples, you scale back your possibilities of transferring to the following spherical.

Thus, having a web-based portfolio is a should. Subsequent, take into consideration accessibility of your portfolio.

  • My suggestion is to publish it on-line.
  • Mine is powered by WordPress.
  • I constructed the location after I was doing search engine marketing years in the past.
  • Then I trashed tons of of search engine marketing weblog posts and retooled.
  • Right here’s my portfolio: https://www.pdgseo.com/portfolio.

There’s tons of website mills on the market to construct a web-based portfolio.

  • I like to recommend GitHub pages & Jekyll.
  • WordPress is a straightforward one.
  • Squarespace affords a pleasant CMS.
  • Decide one and get good at constructing with it.
  • Then improve your portfolio a minimum of as soon as every week.

Keep away from Tech-Heavy Layouts

I ran right into a UK-based tech author just lately on LinkedIn. She has an superior portfolio constructed with github.io. Then powered by Docusaurus. The factor is a beast and jogs my memory of an API doc UI. She additionally has a beefy sidebar that hyperlinks to every writing pattern.

One evening at about 2am after I was engaged on my portfolio, she pinged me. “What do you suppose,” she requested me about hers. Actually, I believed it was far too complicated. I prompt she take into consideration how recruiters would navigate her sidebar hyperlinks.

My level is maintain your portfolio easy. Portfolios promote your stuff. Then get you interviews. Mine isn’t the very best on the planet nevertheless it positive will get me tons-o-interviews. Finish of story.

You’re promoting your self along with your portfolio. So attempt to keep away from teched-out web page layouts. Preserve issues clear and easy. With my portfolio tasks, I’ve 4-8 sentences that describe the supposed deliverables I managed for every firm. Then I embody hyperlinks to the uncooked Markdown recordsdata and revealed articles.

At all times ask your self: can my recruiter consider my portfolio in three minutes or much less? Sure? Groovy. No? Time to transform it and declutter the structure.

Common Customer Period

How lengthy do you suppose hiring groups evaluate your portfolio? Have you learnt?

Based mostly on my portfolio analytics, it’s about 36 seconds. I do know, it’s not lengthy. Particularly since I’ve 40+ writing samples of labor I did for 12 corporations. My level is that based mostly on my analytics, hiring groups scan my portfolio, learn a fast piece of content material or two, then go away.

technical writer

I view the subject of utilizing web site analytics as good to know knowledge factors. That’s it. I’m not promoting hotdog stands or merchandise. So the explanation I take a look at my analytics from time-to-time is to verify persons are spending a while on my portfolio.

What measuring stick do I take advantage of to show my portfolio is making the lower? Interviews and job affords. These are the one two knowledge factors that matter to me.

Portfolio Content material

Approach again within the day, I labored for a nationwide promoting company. I wrote between 25-50 radio and TV scripts a month. Typically extra. We had an enormous shopper record. So my DNA consists of enormous doses of promoting which I nonetheless use in my API doc writing.

So far as portfolio content material, I like to recommend together with the next:

An introduction on the prime of what sorts of technical writing you specialize. For me, it’s 100% API doc writing. I additionally embody a hyperlink to a contact type within the introduction.

api tech writing portfolio

I additionally embody large logos of every firm venture I labored on which seem on the left column. On the appropriate column, I embody 4-8 sentences describing the venture. Then I add the article title hyperlinks (revealed and the uncooked Markdown file).

tom johnson api tech writer
technical writing

Portfolio Colour

As you possibly can see, I selected a black background for my portfolio web page. I really feel it provides higher distinction for studying. All of us stare at white screens all day so why not give busy studying eyes a break proper?

Since my portfolio is powered by my WordPress CMS, I’ve been utilizing the Divi theme by Elegant Themes. You are able to do numerous customization with web page colour contained in the web page widget.

Acquired None?

It could possibly really feel gloomy not having a well-structured portfolio. However what’s worse is having no work historical past to populate your portfolio. Should you’re caught with zero job tasks so as to add to your portfolio, please perceive I used to be as soon as there myself. Ouch, it stinks. However there’s a resolution I used again within the day.

Should you’ve acquired none, and are able to construct your first actual portfolio, right here’s what I like to recommend:

  1. Begin by discovering revealed SaaS articles on-line.
  2. Discover ones which might be clunky and complicated.
  3. Then rewrite each.
  4. Fairly easy huh? Precisely.

I used this format again after I was transferring into API tech writing round 2012-ish. I had no portfolio. So I began rewriting numerous Amazon Cloud docs. Then I moved on to rewriting Stripe API reference docs. It takes time and focus however the advantages are monumental should you commit one hour a day.

When you begin constructing your portfolio along with your new rewrites, embody descriptions the way you up to date the content material and why. Doing so forces you to guage revealed docs and pinpoint gaps within the content material.

One other route is even simpler…

  • Work free for a SaaS venture.
  • Search Google for ‘Crowd doing’ and signup.
  • One other nice useful resource is to pilfer via StackOverflow for volunteer tasks.

The volunteer route takes time and could also be tough to land one thing relying in your entry to decision-makers.


Expert technical writers craft assist content material utilizing the docs-as-code workflow through Markdown. Should you’re new to API tech writing, contemplate studying to put in writing in Markdown. It’s easy and with slightly time, you’ll develop into a professional.

A software I’ve been utilizing for years (together with writing this text) is Stackedit.io. It’s a web-based Markdown editor providing a straightforward consumer interface to put in writing in Markdown.

Not all retailers help docs-as-code. However any API tech gig I’ve landed within the final 5 years positive does.

I’ve labored with many technical writers who despise docs-as-code. Hmmm … I’ve all the time thought. You’re employed with software program engineers. Why not work like them?

When is docs-as-code lifeless mistaken? Normally while you’re restricted by the know-how stack of your employer. In these instances I resort to writing in Confluence. One of many first questions I ask in my interviews is, “How are you publishing content material?” Typically they haven’t any clue. However it’s a great query and one that may maintain you within the plus column for interview efficiency.

Docs-as-code is the only option when managing API docs. I’ve labored on dozens of API doc writing contracts. Quite a lot of had been constructed by well-intentioned builders. Nonetheless, I used to be introduced in to simplify API docs by testing every endpoint. Then rewrite docs to incorporate straightforward code examples and use instances.

Be a part of the Crew

Being embedded with software program engineers is a should for API doc tasks. Attending stand-ups and sustaining open dialogues with devs is the key to writing easy-to-read API documentation. Endpoint testing is crucial to understanding how one can assist new customers onboard shortly to begin pinging APIs.

Hopefully this text helps you type out a few of the widespread pitfalls working along with your portfolio. I want you the easiest in your pursuits.

-Peter Gustafson

About Peter Gustafson

Peter GustafsonPeter Gustafson is an achieved technical author who began his technical writing enterprise again in 2007, whereas being a stay-at-home dad. He juggled shopper calls and diaper modifications throughout these early days. Earlier than his technical writing profession, Peter labored as a senior account government in nationwide radio and TV promoting from 1999 to 2007. At present, Peter consults for blockchain corporations and FinTechs trying to improve their API documentation. When he’s not working, he enjoys spending time along with his youngsters, studying, volunteering, and constantly striving for self-improvement. To see samples of his work, go to his writing portfolio at pdgseo.com/portfolio. You can even observe Peter on Linkedin.

About Tom Johnson

Tom Johnson

I am an API technical author based mostly within the Seattle space. On this weblog, I write about subjects associated to technical writing and communication — comparable to software program documentation, API documentation, AI, data structure, content material technique, writing processes, plain language, tech comm careers, and extra. Take a look at my API documentation course should you’re searching for extra information about documenting APIs. Or see my posts on AI and AI course part for extra on the newest in AI and tech comm.

Should you’re a technical author and need to carry on prime of the newest tendencies within the tech comm, you’ll want to subscribe to e-mail updates beneath. You can even study extra about me or contact me. Lastly, observe that the opinions I specific on my weblog are my very own factors of view, not that of my employer.

Supply hyperlink

Related Articles


Please enter your comment!
Please enter your name here

Latest Articles