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.setPhone(“(707) 555-0328");
           x[0] = y;
           Lead z = new Lead();
           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[1] = new Lead();
           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++) 
  • 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:

Git Demystified for Non-programmers Part Two

At the June, 2016 meeting, Jimmy Cuadra gave the second half of his presentation about the Git version control system. This meeting was summarized by Pete Babb.

While part 1 was an overview of how Git is set up and the basics of commits, part 2 covered Git’s key features: Branching, merging, and collaboration. These functions work via the HEAD reference, which points to the commit you are working on. Any changes you make are applied to the commit the HEAD is pointing at, and you can look at an earlier commit by having the HEAD reference point to it. Making and merging branches is a quick process in Git because of the pointer system, whereas they could take hours in older systems.

Branches silo changes, keeping your main document intact while you try out an idea. Git creates branches by creating a second pointer that points at a commit, and as you make new commits, that second pointer makes them an offshoot of the main trunk. If, after trying out your idea, you decide you like it and want to keep it, you would then merge that branch back with the main trunk.

For example: You’re working on your Master branch and you have an idea you want to try, but you don’t want to alter your Master. You would create a branch (call it “New Idea”) that the HEAD now points to. Now, when you do a commit, the Master branch is no longer affected, as new commits are applied on the New Idea branch. At any point, you can abandon New Idea and go back to working on the Master by making HEAD point to the Master branch again.

If you decide you like New Idea and want to integrate it back into the Master branch, you would use the merge command, which puts the New Idea branch’s latest commit in the Master branch. This is quick and easy as long as the Master remained unchanged while you were working on the New Idea branch.

However, if the Master was altered while the New Idea branch was being worked on and the two branches made different changes to the same thing, you will have a merge conflict. In this case, Git will ask for user intervention to decide which changes to keep. Thus, communication is paramount: All team members need to know what the conflict is so that the team can decide which changes to keep.

Distributed Git is for sharing work with remote team members. It gives each member the whole repository so they can work in their own sandbox. This way, the individual repositories don’t affect each other, so each team member can work independently, and then the work can be brought together via the merge command.

While Git is a very powerful tool, it does not eliminate the need for people to communicate. It’s easier than older version control systems, but people still have to make decisions about which changes to make final. As such, it should be seen as an enhancement to collaboration, not a replacement for it.

The biggest user tip, though, is to not try to learn all of Git or try to remember every single command. It’s a massive system that has a lot of functions writers simply will not need, so it’s more important to absorb general ideas and workflow. The best way to learn it is to use it and pick up on new functions as you need them.

December/January Posts

Here are the recent posts from the STC SF Chapter:

Announcement of Upcoming Meetings

Review of Previous Meetings

  • October 2014 Meeting — Publishing Strategies for API Documentation, presented by Tom Johnson, and reviewed by Mysti Berry

Chapter News