Everyone tells aspiring tech writers to find an open-source software (OSS) project to create content for a portfolio. Unfortunately, while popular advice, I haven’t heard that to be very successful.
Rather than leave you hunting for those elusive OSS opportunities, I’ll describe how the portfolio project I use in my API documentation course works. This approach might be more accessible and achievable for building the portfolio content that you need.
The course portfolio project works because it addresses two critical elements often missing from solo projects: collaboration and accountability. Both are essential skills for technical writers, and both significantly improve your chances of producing something portfolio-worthy.
How to run your own portfolio project
Here’s how our portfolio projects work, as adapted for self-directed learning:
Do your homework first
Success requires going into the project with the necessary technical skills, technical writing skills in this case. This is why we cover the technical aspects of our developer audience, using the tools, organizing the documentation, managing the projects, and so on before contemplating the portfolio. The portfolio project then gives students a reason to put all those skills together.
Students who have had the most successful portfolio projects started with a solid foundation. The good news is that the portfolio project will help you identify the gaps in your knowledge. The bad news is that you might not have scheduled the extra time to learn what you need to know to fill those gaps, which is what makes it frustrating.
While I’d love to see you in my API Documentation course, there are many places that offer courses on API documentation. The important point here is: if you want to develop an API documentation portfolio project, do your homework first. If you want to use the portfolio project to learn fundamentals, make sure your partner is on board and that you’ve allowed extra time for extra learning. (Side note: you’ll want to create a new portfolio after you learn on your first portfolio. Don’t ask me how I know this.)
Find a partner
To achieve real collaboration benefits, find a like-minded writer who has also done their homework.
The ideal partner can provide useful feedback and guidance when you need it. In my course, students pair up, and this partnership is an essential ingredient to a successful portfolio.
When selecting partners, be sure find one who’s got schedule compatibility as well as skill compatibility. My students are usually separated geographically. While meeting in person is great, it’s not a requirement for a successful project. You’ll also need a partner who’s looking for a partner because you’ll both have a dual identity throughout the project.
Embrace your dual identity
In the API documentation course, each student creates a simple REST API using the JSON-server app as a REST simulator, then finds a partner to document it. This looks like the OSS scenario, but with much better odds of finding a willing writer. Each person has a dual identity: subject matter expert (SME) and technical writer (TW).
As the subject matter expert
As the owner and SME of your REST API, you’re the expert on its application and use, but you’re not the technical writer. You make the API available to your partner and answer questions to help them create the documentation.
As the technical writer
You’re responsible for creating all the documentation that your partner’s service needs. You create the GitHub repo and the content, consulting your SME partner for questions and reviews.
The partnership in action
You create an API with JSON-server and find a writing partner to document it. They also have an API. Your partner writes about your API; you write about theirs. Both of you work out how this will progress.
What’s a good project scope?
This only works if both partners have done the requisite homework. Don’t pick a project bigger than your skill set. That’s the recipe for frustration, and your final result will be impressive for all the wrong reasons.
If you’re not ready for API documentation, try something you are ready for. Invent an app (on paper) with a UI and write a user guide. Pick a household item with one of those inadequate manufacturer instruction sheets and give it real, user-friendly documentation. Don’t forget, part of the secret sauce in this recipe is the collaboration, so don’t cheat and document your own (or adopted) product.
As a SME, you should be able to articulate the product’s features and use-cases to your writer. Don’t let them just run off with it. Stay involved. At the same time, don’t create or adopt a product that is too complicated to document in the scope of your project. The key is being enough of an expert to help your technical writer and being enough of a writer to produce useful documentation.
As a technical writer, you should be able to learn what your SME’s app or service does and how it’s used. If it’s something as simple as a toaster, you should understand toaster use-cases or be able to learn them. If the SME’s product is too complicated, see if you can negotiate a simpler product or find another SME.
Establish a schedule
Agree on a schedule; both for your success and sanity. The project should take more than a few weeks but be presentable in about six weeks. If not, you’re overthinking it or you’ve over-scoped it. Longer than six weeks, it’s easy to lose interest (and hope). Shorter, you won’t have time to iterate and improve.
Make sure your schedule has weekly deliverables. Iterate with your partner so your projects stay in sync. This prevents your working relationship from becoming dysfunctional.
In my API Documentation course, the portfolio takes six weeks and includes examples of each type of documentation. Usually, the portfolio documentation has a total of 10 pages that cover four different types of documentation. Clearly not a complete set, but enough to show your skills. Besides, you can always keep adding pages after your team project “ends.”
Engage in frequent peer reviews
Plan for weekly peer reviews of new content, organization changes, or other developments. You should have something new and review-worthy each week.
Bonus points if you can recruit people outside your team for feedback. Consider Guerrilla Usability Testing as a way to get additional feedback.
The usability testing usually provides the most useful feedback (just as in real life, by the way). As web-based documentation, you can send out a link to your documentation with a questionnaire to get feedback, if you can’t find anyone local (just like in real life…hint, hint!).
Keep weekly reflections
Maintain a journal of weekly reflections about how things went, new insights, recent challenges, and anything else about your project. Include screenshots, sketches, and other visuals.
The goal is to reflect what you learned and how you learned it. This becomes valuable when you present your work and discuss your process with potential employers.
Present your results
Create a presentation of your work that goes beyond just the URL of your documentation. Tell the story of your documentation and include the how and why behind your final result.
Good presentations have a hook, a short personal story, or some other way to draw the viewer in. The sad reality, unfortunately, is that most employers won’t look at anything but a couple of sample documents, so the presentation’s biggest value is to identify and practice the stories and examples you’ll use in an interview.
Keep updating
Once you’ve completed your initial portfolio project, continue improving it as your skills develop. Your portfolio should evolve with your capabilities.
Stop waiting for that OSS project made of unobtanium and start writing!