President’s News and Notes

By Leah Scampoli

Although I wasn’t able to attend this year’s STC Summit, I did take a look at the track descriptions. That got me to thinking about how the themes have changed over the last few years. Comparing the last five year’s track descriptions, I noticed that, aside from a few lineup changes, the track descriptions have remained mostly unchanged. However, there was interesting recent development.

Early on, Web Technologies was a mainstay. However, this year, Mobile Content Design and Development made an appearance as Web made its exit. I don’t think it’s necessarily that writing for the web is any less important, but more that writing for the web is now an emerging and vital skill. With improved smart phones and tablets, more and more people are viewing the web and other applications on their portable screens. This type of viewing is very different than reading off of a large monitor and presents a new set of challenges–and skill set. I can only assume mobile will continue to be part of future summit tracks.

Much like the rise of wikis and user-contributed content changed the technical writing landscape, the omnipresence of smart phones and tablets (and the possibility of watches and glasses) seems to be a trend that will only grow in importance. I think that the STC has done a great job by placing the topic on its track lineup to keep its members ahead of the curve.

Do you have any STC Summit stories to share? Email info@stc-sf.org to submit your thoughts.

Thanks, Leah

President’s News and Notes

By Leah Scampoli

A few months ago, I was placed onto a new project at work: API reference documentation. It’s been challenging, rewarding, confusing, and frustrating–all at once.

I’d never worked on API documentation before, which I don’t like to admit in the company of other technical writers who seem to all be experts in this arena. But, for whatever reasons, I’d mostly worked with consumer documentation, no less technical or difficult, but definitely different. It’s only been the last couple years that I’ve edited developer documentation or written instruction sets for developers. But, never traditional API reference information.

I was lucky enough to be put on the project at work and have the support of an amazing team of product managers and developers to work with, who understood my inexperience writing this type of documentation but had enough faith in me to still produce high-quality documentation without putting too much of a burden on them.

Early on, I started researching how other companies were presenting their API reference documentation, both to get an idea of what was required and to compile some best practices. Together, the team and I identified Amazon Web Services and eBay as having some really great examples. It made sense given that these companies are large and well-established that they would have the resources to devote to documentation. Although smaller, start-up type companies tended to not have such polished documentation, it was always a pleasure to come across a company that had clearly prioritized documentation.

With so many great examples, it was a fun process to pick and choose the best ideas to use in our documentation. As this was a new service and there was no API reference model so far, I had the unique opportunity to create documentation from scratch, without any constraints on consistency or style. This allowed me to create something that was user driven.

Of course, this was only possible because of the great support from the team. Not only did they make the time to review the documentation, they provided really insightful feedback on what a developer would–and wouldn’t–need and like to see in the documentation. It was refreshing to work for a team that understood the importance of documentation. For instance, time was taken to perform usability testing on the tutorials. I’d always heard of, but never thought I would be part of, such type of invaluable, but rarely realized, documentation testing.

That’s not to say that there haven’t been challenges. It was difficult to learn everything about API documentation in a short period of time. Learning new terminology, new tools, and the basics of programming was something I always knew was part of technical writing, but something I hadn’t yet come across in my career.

Sometimes I was confused and frustrated that I wasn’t getting it quicker. But, with a little patience and yogic breathing, I was able to finish the documentation on time for the first, major milestone. It’s in no way complete, and there’s a lot to add. But, it’s been no less rewarding to hear compliments and congratulations.

I’m really appreciative that I had such a great first experience with API reference materials, and I look forward to expanding and building upon what I’ve learned to create even better documentation.

Thanks, Leah

President’s News and Notes

By Leah Scampoli

At the time I’m writing this, it’s the weekend before Thanksgiving. Besides making food shopping lists and dreaming of leftovers, it’s an appropriate time to give thanks to the absolutely amazing volunteer team for the Chapter. Andra, Keith, Marc, Marie, Monica, and Riley make each newsletter sent out, LinkedIn or MySTC article posted, announcement emailed, treasury report created, and meeting organized.

But, we need your help.

In order to give our team some extra time and to allow the Chapter to expand our offerings, we need additional volunteers. We understand that between work and at home time, little time is available. But, there are many opportunities that take only a few hours a month or can be done remotely. In addition, many can be handled by multiple people to spread the load.

Do any of these positions sounds interesting to you? If so, email info@stc-sf.org for additional details.

  • Hospitality Manager
  • Programs Manager
  • Webinar Manager
  • Marketing Manager
  • Assistant to Webmaster
  • Assistant to Newsletter Editor

Building our volunteer base allows us to offer more to the technical writing community in San Francisco. Looking forward to 2014, which always begins to happen at this time of year, we hope to offer even better presentation topics. I am also especially excited that we have been exploring how to offer those who can’t attend the meeting in person to log in remotely to experience the presentation. By offering webinars, we hope to increase our circle of presenters and allow those outside of the Bay Area (or those who can’t always make it into the City that night) the opportunity to join us, albeit virtually.

It should be an exciting year, and I hope you can join us!

Thanks, Leah

President’s News and Notes

By Leah Scampoli

Recently, my department at work has been deciding how to update our newsletter. In researching best practices for business to business electronic newsletters, I found that although there are many sites that touch on the topic, relatively few have a concise but complete list. I thought I would share a couple of websites that I visited and some of the tips I gleaned. Of course, as each project has different needs and audiences, not all of the tips may apply to your own enewsletter circumstances.

    • Skimming and Scanning Along–Most people read online content by jumping around the page and only stopping when they pick up something of interest. One stat I saw was that people spend under a minute (!) reading a newsletter. To facilitate this type of reading, think about how you can make it easy to quickly review a page to find the information that is most important and applicable to the reader. For instance, make use of descriptive headers to jump to sections of interest, bold and underline styles for important information, and plenty of whitespace to avoid crowding. As is for mobile and online writing, short paragraphs are key.
    • Short is Sweet–Building upon the idea of short paragraphs being easier to scroll through and comprehend, having a shorter article and even entire newsletter length is also advantageous. The suggested number of articles and words per article vary, but the idea remains the same: people can only absorb so much information. I know that when I look at a newsletter and it seems long and overwhelming, I’m more likely to skip completely that muddle through. Of course, this all depends on the purpose and audience of the newsletter. Speaking of…
    • Know Thy Audience–This idea came up quite frequently among the top tips lists I read. Of course, being technical writers, I think we all have this tattooed in our memories. So, no need to elaborate.
    • Give them a Call (to Action)–Sometimes it’s hard to remember that amongst all the great information you’ve laid out for a reader, it’s not completely obvious what they need to do next. But, to get the response you want, you need to tell the audience what they need to do in no uncertain terms. For me, I always think about those medical benefit or financial letters I receive. There seems to be a lot of information that may or may not be useful, so I’m always grateful for that bolded text “There is no action needed on your part” or “You must complete this form.” Maybe the call to action is more vague (Join us on Twitter!) but audiences appreciate knowing what they need to do nonetheless.
    • Image isn’t Everything–Sure, fancy graphics and background make the final product look pretty. But, it’s not always the best move. For one thing, too many images can distract from the content. In other cases, for compatibility or security reasons, email services block images. So, all that time spent turns into empty boxes. This isn’t saying that you shouldn’t consider the aesthetics of the final version, but, like a lot of things, don’t overdo it.
    • Keep it Fresh–No one likes stale content. And, enewsletters shouldn’t be different. Even if you want to mix older pieces in with the new stuff, make sure there’s a distinction and the more current content is more prominently displayed. That last point is important and brings us to…
    • Remember the Triangle–As anyone who took Journalism 101 will tell you, the inverted pyramid is king (or pharaoh) of article construction. Front load the story to have the big takeaway, the latest news, and the 5 Ws in the first ‘graph (to continue using the lingo). If people only read one thing (and sometimes they will), at least they have the most important information. Expanding this to the entire newsletter, put the most important stories up top (or use a table of content with hyperlinks). This becomes even more vital for how enewsletters are first read: in a preview pane. If that small box doesn’t have something that catches a reader’s eye, off to the trash folder it goes, unread.

 

Want to keep reading up on this? Here are some of the websites I visited:

I hope this helped you if you were considering how to best update your enewsletter. Do you have any advice or suggestions to share? Email info@stc-sf.org.

Thanks, Leah

 

President’s News and Notes

By Leah Scampoli

At our June meeting, presenters Dee and Pamela gave a great presentation about information delivery in the age of interaction. Besides sharing some useful and thought-provoking information, the presentation included some terrific graphics. One slide of the Dos Equis Guy giving advice (Google “I don’t always test my code” for a laugh) got a great response. But, it was the slide of various Facebook mantras, for lack of a better word, that got me thinking. Although written more for programming, I thought it was interesting to consider how those ideas bleed into technical communication.

Done is Better Than Perfect

I’ve been working in the highly regulated financial and biotech industries for a while. So, right off the bat, I wouldn’t say that non-perfection has ever been a goal. In fact, it may be the opposite: Perfect is Better Than Done. When safety or privacy is at stake, double checking the documentation that last time (even if you’re down to the wire) has always served me well. It’s hard to be the person to say “hold up, let’s think this through” when everyone wants to get something out the door. But, having a level head in chaotic environment is just what is needed sometimes.

Although more than slightly pretentious, I once proudly carried a bag with “Someone still cares about quality” on it. I think that I take pride in being the person on the team who wants a perfect result more than a quick one. As we live in the real world, that’s easier said (or screen printed on a bag) than done. Nevertheless, I still strive to keep that in mind, and I always appreciate it when I work with a kindred spirit.

What Would You Do if You Weren’t Afraid

I think that this question has resonated with a lot of people outside of their career. In fact, it’s taken up a life of it’s own for a campaign for young women. But, I think it’s also a valuable question to ask at work. By thinking outside of your comfort zone or usual company box, it makes you question more often and with less timidity. I think one of the most cringe-inducing phrases is “well, that’s how we’ve always done it.” Yes, consistency is important, especially in documentation, but the foolish sort is also the hobgoblin of little minds, according to the good man Emerson. I’ve found that freeing myself of what the department did in the past often leads to more efficient and effective processes and output.

To look at it another way, the idea of not being afraid of making mistakes is a powerful thought when you’re stuck in the how-do-I-start-this-document mud. I recently went to the Richard Diebenkorn exhibit at the De Young. There, amongst the art he created during his time in Berkeley, was his “Notes to Myself on Beginning a Painting.” The one that resonated most with me and the one I think connects to the saying was “Mistakes can’t be erased but they move you from your present position.” It makes me think of what I do when I am faced with a blank page and that horrible blinking cursor: I take a breath and start writing, unafraid. Luckily for us writers, there’s a delete button.

So, what do you think? Are these mantras applicable in our tech comm world. Do you have any of your own? Contact us through email, Twitter, LinkedIn, and MySTC to share.

Thanks, Leah

President’s News and Notes

By Leah Scampoli

My favorite part of coming to our monthly meetings, besides seeing the familiar faces, is when a couple weeks or months after the meeting I have an opportunity to implement what I learned during a previous meeting. There have been a couple of such occurrences recently that I’d like to share with you.

A couple of weeks ago, I bought a film camera, or what the kids today are referring to as an “analog” camera. (Insert eye roll here.) Not having loaded film in over a decade, I needed some guidance. Sadly, the manual, or more accurately the leaflet, was both incorrect and incomplete. But, thinking of our February meeting on instructional videos, I turned to YouTube. And there I found several good Samaritans who had made a suite of videos about my model of camera. Although I wish a couple of the video posters had come to our meeting to learn some tips, I got the information I needed. From unpacking the box, loading/unloading, and taking the first picture, You Tube had it covered where the manual and company website fell short. It both brought a real life application to the information I learned at the meeting and gave me something to think about concerning the future of how people get instructions.

Another meeting was about LinkedIn and, specifically, getting yourself noticed. Again, a couple of months after the meeting, I ended up catching up with a couple of friends who were looking for a new job opportunity. It was a great feeling to be able to offer some usable and helpful information that I learned during the meeting to my friends. Luckily, that meeting’s presenter, Andrew Davis, did a great job in giving some specific and rememberable tricks of the trade that I could pass along. I went into the meeting just thinking I could improve my own LinkedIn game, but as it turned out later, I actually left the meeting with information that could help a wider audience.

Do you have a similar experience about taking what you learned from a meeting and applying it during work or play hours? Tell us on Twitter @STCSanFrancisco, MySTC San Francisco Chapter, or info@stc-sf.org. We’d love to hear from you!

Thanks, Leah

 

President’s News and Notes

By Leah Scampoli

 

Recently, there was a thread on the STC LinkedIn Group called “Don’t Touch it!; Technical Writers Have a Sense on Humor.” Although the title referenced an oddly documented (and possibly constructed) vacuum cleaner, I like to think of the title of the discussion thread more as exhibit A that we aren’t serious grammar police all the time.

I’m sure we’ve all got some comedy material about the Oxford comma. We keep some crumpled unintentionally hilarious instruction printout somewhere in our desk. We laugh at Scott Adams’ Tina the Technical Writer’sexasperation. Besides a knowledge of communication best practices and what DITA is, humor about technical writing is one of the things that bonds us communicators together.

I know that it’s one of the things I’ve missed not working in a technical writing team these last couple years–and one of the things I’m looking forward to starting my new job with a large tech writing department.

Humor is not always the best reaction, however. I remember during my first writing job, an important email from the department head had gone out with a wrong hyperlink. An annoyed and frantic co-worker hurriedly explained the situation to me, as I hadn’t worked on the original email. I heartily laughed (to re-emphasize, wrong reaction) and told her that due to everyone clicking the wrong link, it had overloaded the server. Sensing she didn’t share my amusement (tough crowd!), I quickly shifted gears to explain how we could update the website’s link to match the email’s link while the server was recovering without anyone being the wiser.

So, you can see that with my tendency for nervous joking, I was happy that there’s evidence of other technical communicators who have a sense of humor. Now I just have to find the right moment to launch into my joke about DITA Von Teese, the XML data burlesque model.

Thanks, Leah