March 8: Expose UX and General Assembly SF Conference About Gender Parity in Tech

Join Expose UX and General Assembly SF for a tech-focused celebration of International Women’s Day on March 8, 2017. Observed worldwide, this year’s theme is #BeBoldForChange: celebrate and declare bold actions taken to help progress gender parity in tech.

Network with other techies and share your bold actions, watch a special Expose UX episode featuring two female entrepreneurs, then learn from a panel discussion with local women tech leaders about their bold stories.

Agenda

  • 6:00 Networking
  • 7:00 Welcome / Expose UX Screening
  • 7:45 #BeBoldForChange in Tech Discussion Panel
  • 8:30 More Networking (until local leaders decide to end)

About #BeBoldForChange in Tech Discussion Panel

Local women in tech explain that exact moment when they themselves took bold action to improve or develop an aspect of their own livelihood, career or business – or that of another woman’s, or women’s status overall. They’ll discuss what constitutes bold action, the conditions necessary to enable bold action, and what it’s consequences are.

About Expose UX Screening

Watch a special episode of Expose UX, the web show where user experience experts help startups improve their products. Filmed at the international Ladies that UX conference, Talk UX, two women-lead startups showcase their talents. One helps blind people perform tasks on inaccessible websites, the other is a tracking device to protect victims with restraining orders.

Judged on their UX Research, Interaction Design, and UX Strategies, the episode triumphs women entrepreneurship while teaching user experience concepts. Featured guest experts are Marti Gold, Managing UX Director of Tonic3; Amanda Stockwell, former VP of UX at 352; and Kelley Mitchell-Price, Global Creative Director for InterContinental Hotels Group.

Happy New Year: Some Exciting Changes to Our Monthly Meetings!

Happy 2017 technical communicators!

With the new year comes a few exciting changes for the SF Chapter.

First of all, all of our monthly meetings are now free for everyone. Whether you are an STC member or not, you get in for free. This also means that we won’t be offering student discounts or free meeting coupons. It’s free coupons for everyone.

Now, why still become a STC member or join the SF Chapter through the STC? Because your generosity is how we can offer free meetings for everyone. That $25 due goes a long way to provide sandwiches for guest, keep this website running, and pay for our PO box. We sincerely hope that you get enough enjoyment and education from our monthly meetings to continue making us your home chapter.

Not an STC member but still want to contribute? We’ll have a tip jar at the meetings, plus a virtual tip jar on our new Meetup page. It’s easier than ever to register for the meeting. You’ll get reminders and get to see who else is attending.

Why register at all if there’s no charge. We use this for the all important sandwich ordering. Plus, since we’re still at the Salesforce office, it makes checking in faster for you.

Here’s wishing you a great year. Hope to see you and catch up in January!

Intern Needed!

NGINX is a fast-growing startup located in San Francisco in the South of Market area (SOMA). We are seeking an intern to work with our Marketing team, contributing to our popular blog at https://blog.nginx.com. The internship position is paid on an hourly basis.

The ideal candidate for this internship will be:
– A current or recently graduated college student
– Seeking to major in computer science, communications, marketing, or a combination
– A crisp, clear, and concise communicator, in written and spoken communications
– Analytically minded; math skills appreciated
– Aware of search engine optimization (SEO) and how SEO is used in marketing
– Aware of web server technology and how web servers are used in websites and apps such as Amazon, Airbnb, and Uber
– Work experience related to technology development (from startup to Fortune 500)
– Available up to 20 hours a week for next few months, mostly at our offices

Also desirable: High test scores, good grades, print or online publication of your work, and other supporting information relating to the qualifications above.

Writing Code Samples for API Documentation

For the September 21, 2016, meeting, Joe Malin discussed writing code samples for API documentation. This meeting summary was written by Michelle Mills.

When we write API documentation our audience always already has a basic understanding:

  • Millennials have used computers since high school; all are computer literate
  • Diverse professionals (accountants, graphic designers, etc) probably know what they are and want to utilize them
  • All users are therefore also developers

Code samples are important

  • Developers want to be able to copy code from documentation
  • Code samples are fairly complete apps (not a description or tutorial)
  • Shorter is usually better (long is often too specific; specifics can be addressed in footnotes if necessary)
  • Inference links outside your organization are discouraged (continuity and accuracy cannot be guaranteed)

Your documentation should:

  • Illustrate patterns and tasks
  • Promote copy/paste
  • Be simple
  • Be applicable to “real life” issues
  • Be high quality:
    • Solves real-world problems
    • Uses programming language standards
    • Provides working samples

What is a pattern or task in API documentation? Examples include:

  • Security (OAUTH identification)
  • CRUD (create, report, update delete)
  • UI, including:
    • App navigation
    • Enhanced effects (animations, carousels)
    • Responsive UI

Specific example: Good pattern/bad writing

From Salesforce SOAP API documentation API (freely available); used to convert a “lead”:

public String[] conv() {
     String[] result = new String[4]; 
     try {
           Lead[] x = new Lead[2]; 
           Lead y = new Lead(); 
           y.setLastName(“Malin");
           y.setFirstName(“Joe");
           y.setPhone(“(707) 555-0328");
           x[0] = y;
           Lead z = new Lead();
           z.setLastName(“Scampoli");
           z.setFirstName(“Leah");
           x[1] = z; 
           SaveResult[] retr = connection.create(x);
…
} catch (ConnectionException e) }

Some problems:

  • No comments
  • Nonspecific variable names (i.e. x)
  • Shortened string variable names (conv instead of convert or convertLead)
  • Where did ConnectionException come from?

Code corrections for above example:

// Convert a Lead into an Account and a Contact
// Based on Enterprise WSDL setup
public String[] convertLeadRecords() {
      String[] results = new String[4];
      EnterpriseConnection myConnect; 
      try {
           Lead[] Leads = new Lead[2];
                Lead[0] = new Lead(); 
           Lead[0].setLastName("Twain");
           Lead[0].setFirstName("Mark");
           Lead[0].setPhone("(800)555-1212");
           Lead[1] = new Lead();
           Lead[1].setLastName("Austen");
           Lead[1].setFirstName(”Jane");
           SaveResult[] results = myConnect.create(Leads);
…
      } catch (ConnectionException connectExcept) }

Common coding errors that are easy to catch include:

  • Poor naming conventions:
    • using foo or x
    • Non-standard naming conventions, such as:
public class Myclass {
  • Non-standard indentation, such as
for (int i = 0; i < 10; i++) 
 { 
myFunc(); 
 }
  • Forgetting the variable’s name, such as:
var destSite = ‘http://www.example.com/rest1’
…
response = sendRequest(destURL);
  • Accidental misuse of = and ==

Always test your code sample to be sure it works!

Good code samples include:

  • Samples that adhere to the styleguide
    • Use company-standard icons
    • Data input labels below input
    • Test on small devices
  • Coding guideline examples:
    • Mutable variable: mIncomingEvent
    • Constant: SECONDS_PER_MINUTE
    • Package names: com.example.sampleapp
  • Commenting guidelines and examples:
    • Use line or block, not both
    • Add to the sense of the code – don’t just restate the obvious
    • Add licensing info to every file (tech writers need to understand licensing and/or ask manager or legal.)

Take a piece of raw code, and apply your style, commenting, and coding guidelines. You can also generate snippets or gists from a raw code example.

Resources for licensing information:

  • Choosealicense.com
  • Github repositories

Resources for code examples:

Getting Involved in the Technical Writer Community

On September 14, 2016, SF Chapter president Leah Scampoli presented at the Berkeley Chapter’s Job Fair on why writers should be more involved in the technical writer community. This is a copy of the prepared speech.

Today, I’m going to talk about how to get involved in the technical writing community–and why it’s such a fantastic idea.

So, a little background about me. In 2005, I was a wee baby technical writer, having just graduated from State Francisco State University’s Technical and Professional Writing Program. I went to my first STC SF Chapter meeting, which happened to be the Christmas party. I remember walking to the meeting at the old Elephant and Castle and feeling very nervous. I was about to be in a room full of real technical writers. People who knew a lot more than I did. But instead of feeling self-conscious about my entry level status, I felt so welcomed. Everyone was so enthusiastic to meet a newbie and share their thoughts and encouragement. I walked away feeling energized. I was also the new Hospitality Manager for the chapter.

Over the last 10 odd years of my career, I’ve grown a lot. I worked briefly in the financial sector, then several years at a couple of biotech companies, writing clean room certification reports, clinical trial data management software testing reports, and technical docs for medication databases. Now, I have a #dreamjob at Salesforce writing about how our search works. Along the way, I’ve also grown at the STC SF Chapter. From Hospitality Manager, to Secretary, to Vice President, and now President/Treasurer/General What Needs to Get Done Resource. So, you can tell that I’m pretty passionate about getting involved in the technical writing community. I’m here today to tell you why you should be passionate about our community as well.

The first and most obvious reason is  probably the most appropriate for this job fair. Getting involves gives you  great networking opportunities. I’ve gotten two jobs through the SF Chapter, and both were really milestones of my career. The first one was my very first technical writing job at Wells Fargo. At the meeting, a woman stood up and said she needed an entry level writer. And I sprung at the opportunity. The second is my current job. I had volunteered with another writer at the SF Chapter for a while before talking to her about a career at Salesforce. Being in a room with other writers, whether it’s at at a local meeting or an international conference, is a no-brainer for networking opportunities.

Secondly, being involved in the technical writing community offers a great chance to learn from others or share your own ideas and experiences, especially if you’re a lone wolf writer. I’ve been there, and it was such a wonderful feeling to be able to share problems and experiences with your own kind. Yes, there are online webinars, forums, and blogs, but it’s really not a substitute for being in the same room with a group and having that one on one interaction and flow of ideas. I’ve gone to most every SF Chapter meeting, and even when a certain topic didn’t immediately impact my job, I’ve gotten value. Often, though, topics have immediately impacted my job. Quite a few times, I’ve excitedly reported back to work about a topic with ideas on how we could implement it in our group. Salesforce was the first job where I used DITA. Thankfully, I had a pretty good idea about it given that for a couple years, it was the ever-present topic in technical writing circles. In another case, the great ideas from the community around API docs really helped me when I had my first major API doc set to write.

And meetings aren’t just about taking in information. Meetings offer a great opportunity to volunteer and beef up your resume, either with writing samples or project management skills or people skills. You can write an article for the newsletter or chapter website about a meeting or any related tech comm topic. In addition, I’ve learned so much about working with people by working with the volunteers and guests at meetings. Meetings also offer a chance to improve your public speaking skills, since they’re always looking for speakers. Presenting to your peers at a meeting is a great way to practice talks not ready for conference prime time, while getting thoughtful feedback on your ideas. For me, I know that having to get up consistently to speak at our monthly meetings, even for the silly chapter updates, has made me a better public speaker.

Finally, and this is a little more hippie sounding, but I feel that being part of a technical writing community is good karma. By that I mean that technical writing is my career, it’s my work passion, and it’s given me a lot of opportunities in life. I feel that because I’ve gotten so much, I want to be able to give back and help others.

OK, I’ve talked a little about the benefits about being involved in the technical writing community. But, how would one go about it? There are a bunch a ways. Our SF Chapter website has a Resources page with a bunch of links for you to check out. I’m going to go through a few good ones to get you started thinking.

First, you’re probably familiar with a little group called Society for Technical Communication? They have this thing called Chapters and Special Interest Groups, which host meetings. 😉 Obviously, I’m biased to the San Francisco Chapter, but all the Bay Area chapters do amazing work and are worth checking out. A lot of chapters have special events, like this one. Another event is the Touchstone competition, where you can enter your best documentation examples for review. Being a judge for Touchstone is a great way to become part of the technical writing community.

Another group you may or may not be familiar with is Write the Docs. They have monthly meetups in various places in San Francisco where the format is similar to an STC Chapter meeting. Some topics have included API docs and videos. They also have a YouTube channel and a Slack channel if you want to catch up or reach out to others outside of the meetings.

Next, let’s talk conferences. Of course, there’s the big annual STC Summit, held earlier this year in Anaheim. The next one is May 2017 in Washington DC, so you have plenty of planning time. I don’t think there’s a larger gathering of technical writers anywhere on the earth, which is pretty exciting and very nerdy. Obviously there’s the talks, which are great. But, if you want to really be part of the community, conferences are a great way to talk in person with the people you usually just read online.

I volunteered at one of the first TC Camp, which is the techcomm unconference. It was a blast! First off, it’s local and it’s a great deal, price wise. It calls itself an unconference because the topics discussed are driven by the members of the community, not some conference judging committee–so you get to be part of the discussion on what’s important. It’s also run by some amazing members of the community, so I can’t recommended that one enough.

There are a bunch of other conferences too:

Finally, another way to get involved is to reach out to local colleges that offer technical writing degrees or certifications. For more experienced writers, colleges are an amazing place to find quality interns or entry level writers. We all have been there and wanted a little help in our first years. Plus, having a new perspective works wonders for teams–and it’s a great feeling to mentor the next generation of writers. Both San Francisco State University and UC Berkeley Extension are great places to start.

So, in summary, here are my takeaways. Getting involved in the technical writing community is a good idea because it’s a great way to network, to add to your resume, to share ideas, to learn from others, and to give back. There are tons of ways to get involved. Think about entering a competition, visiting a conference, going to a meeting, and reaching out to a tech writing college program.

Touchstone 2016-17: Call for Entries

Be Recognized for Your Technical Documentation! Northern California Technical Communication Competition Touchstone 2016-17 call for entries is now open.

About Touchstone

Touchstone advances the field of technical communication by recognizing outstanding work. Touchstone awards can bring recognition from professional peers and increased visibility with employers and clients. The competition will culminate in an awards ceremony in January, 2017.

Workplace awards presentations may be arranged for those who request them. Workplace presentations are often attended by entrants’ peers, managers, and company executives. Touchstone’s experienced judges also provide feedback to help entrants improve their work. Many entrants prize this feedback as a valuable benefit of having entered. Top award winners in the Touchstone competition are sent on to compete in the STC international technical communication competition.

Beyond the direct benefits you receive from entering the Touchstone competition, its existence and continued success help to educate clients and employers about the value of what technical communicators do. Competition proceeds support the STC Kenneth Gordon Scholarship. The Gordon Scholarship benefits the profession by providing scholarships to students in technical communication programs in Northern California.

Call for Entries

The 2016-17 Touchstone Technical Communication Competition is now accepting entries in the following categories:

  • Technical Print Publications and Documentation
  • Online Technical Communication
  • Technical Art

The deadline for entries is Saturday, October 8, 2016. 

More information and instructions on how to enter.

Berkeley Job Fair: September 14, 2016

The STC Berkeley Chapter is hosting a Job Fair on Sept. 14th, from 6-9PM at Ed Roberts Campus above Ashby BART Station.

Looking for a job? Want to mingle with some peers in the industry? Want to brush up your resume or portfolio? Want to chat with some recruiters? Want to hear the sage advice of industry professionals?

SAY NO MORE!

The STC Berkeley job fair is a great opportunity to meet fellow technical writers in the area on the hunt. Whether you’re hiring, looking for a job, or holding your ear to the ground, there’s a place for everyone at the STC Berkeley job fair!

It features a progression, in which small groups meet with industry experts to discuss topics about technical communication and job seeking.

We’ll also have resume counseling, lots of networking, and light refreshments.

Don’t forget to register!