Recap Part II: Portfolio 101 Panel

The next session in the Portfolio 101 workshop was a roundtable discussion with Alexandra Dermigny, Catherine Sprankle, Lois Shank, and Tony Russo who discussed what makes an outstanding portfolio in their respective industries.

Panel speakers: 

• Alex Dermingy (Specialist for training and development content in financial professional services)
• Cathy Sprankle (Science Writer and Manager for publications for different govt. agencies)
• Lois Shank (Project Manager focusing on Dita and XML from health communication and medical background)
• Tony Russo (API documentation specialist and has experience in digital publishing too) 

Portfolio for Learning and Development (L&D) industry

Speaker: Alex Dermigny 

Alex briefly explained the role of L&D professionals in the financial services domain, and offered some tips on developing portfolios for L&D professionals.  

There are four key elements to telling your L&D story:

• Demonstrate your change readiness: Showcase how adaptable you are, especially in these changing times. You can show some examples, such as switching from in-person to online training, planning for a virtual conference, or switching  to a virtual onboarding. Add information about what interactive elements you added in your module to suit the virtual medium. 
• Demonstrate breadth and depth: Try to show multiple skills. Flex other skills you picked up along with your job. For example, explain a new tool that you learned, and support others to learn the tool. More than a tool expert, be a strategy expert. 
• Know your learners: Show that you did your homework to reach your learners. 
• Include TL;DR summaries: TLDR (or TL;DR) is a common internet acronym for “Too Long; Didn’t Read.” In its simplest form, TLDR is used to express that a piece of digital text (an article, email, etc.) is too long to be worth reading. Know your portfolio audience, and include some slides that are TL;DR summaries for readers who might get overwhelmed with the different portfolios that are on your site. 

The following screen capture is an example of TL;DR summary for a process document:

Portfolio for science writing industry

Speaker: Cathy Sprankle

In biomedical research companies, the most-frequently created documents are as follows:

• Technical reports
• Science communication
• Manuscript and publication editing and production

 For the science writing industry, your digital portfolio should:

• Demonstrate your mastery of Microsoft Word; Scientists want to work in Word, and not use any structured authoring tools 
• Show that you can work with PDF file formats
• Establish that you have an eye for detail
• Align with an in-house style guide, a journal’s style, or a broadly accepted style such as APA
• Showcase clear, concise writing
• Include you as an author or name you in the acknowledgments
• Show that you can collaborate and handle feedback
• Demonstrate initiative and ability to work independently
• Exhibit a love of writing
• Display your life sciences knowledge

Portfolio for Healthcare industry

Speaker: Lois Shank

In the healthcare industry, Lois’s team does not insist that writing samples be examples of healthcare documentation. They just want to see samples that reflect the types of documentation that they delivered, and the most frequent document they deliver are task documents. Lois’s team specifically looks for writers who are trained in DITA,  because they work in DITA and DITA can take a long time to learn for some writers. 

To create a portfolio for a job in the healthcare industry, you can:

• Go to a healthcare provider, such as a doctor, and ask them if they have any documents to revamp. As you revise the document, make notes about why you made the changes that you did.
• In your online portfolio, do talk about your sample and your thought process. See an example: https://straygoat.co.uk/flare-sample-2/Content/about-sample.htm
• Volunteer to document for Tech Writers Without Borders (https://techwriterswithoutborders.org/)
• To show your skills to work on a writing team as a new writer, you can work with your tech. comm. batchmates and document something together as a team. Alternatively, you can find some other writers in the same situation and find something to document together.

Portfolio for API documentation

Speaker: Tony Russo

Tony gave some tips on writing effective API documentation. He also gave a walkthrough of the API documentation process tools and processes. 

From paper to web to on-demand, effective writing is about connecting with your audience – whether they are eager readers or customers. Good technical documentation explains concepts and reduces customer support questions. Better technical documentation improves customer attitudes towards your products and services. 

Some types of API documentation are as follows:

• Swagger: A text file with .YAML extension, the swagger format describes an API’s methods, parameters, responses, and errors. The free Swagger editor can view and edit YAML. Programs like Postman can import Swagger YAML files so developers can test an API’s methods.
• Markdown: A text file format that is much simpler than tag-based HTML and XML. Markdown is the preferred documentation file for code repositories such as GitHub.
• On the web: By using a combination of YAML, Markdown, HTML, CSS, jQuery, and other tools, API documentation can be presented with content within a dedicated website. 

Following are some examples of API doc samples that Tony created: 

• https://drive.google.com/file/d/1ZdXB2N7BHz66Ja-qoPKi65pHljlOSyz1/view?usp=sharing
• https://drive.google.com/file/d/1RQYm2u2aAcdb_HYWNygiLWSeM_TCRw2r/view?usp=sharing

The following is a website conversion tool which takes a Markdown file and creates a website: https://github.com/mpociot/whiteboard