Meet the New Generation of Technical Writers at San Francisco State

At the July, 2016 meeting, Neil Lindeman, Ph.D., Associate Professor at San Francisco State, talked about the Technical Writing Program at SFSU as well as their Internship Program. This meeting was summarized by Floyd Smith.

STC-SF Meeting: Wednesday, July 20th, 2016

Leah opened with announcements.

Neil Lindeman, SF State

Director of Technical Writing Program

Ex-editor at Conservation International

Meet the New Generation of Technical Writers at SF State

Technical and Professional Writing – Only major program in California!

  • Program dates back to early 1990s.
  • Golden age through dot-com boom and even to ’08 financial crisis. They’re rebuilding now from some lower enrollments and funding challenges. DITA and online help courses have gone missing, with 20-student minimums. They are now more online-oriented.
  • Administratively, they’re becoming a concentration in the English major. 30-40 active major students and 20-30 minors (24 units = 8 classes), plus certificate program w/5-10 people (same requirements as minor).
  • Focus can be technical writing or development work etc., which is professional writing. 30% go to tech writing, rest want to be less technical.
  • Required: Fundamentals class, “technical promotional writing”, document design. Minor of some kind; can be information systems, instructional technology, computer science. For professional writing, can be marketing, non-profit communications, graphic design.

Internship Program

  • Students who are near graduation.
  • Develop job application materials, including coursework.
  • Length is 120 hours of program-related work, ideal for it to all happen in one semester (16 weeks).
  • Students need to be pro-active about finding internships. About one-fourth of internships are paid (perhaps $20/hr) and three-fourths unpaid.
  • Internship sponsor evaluates the student and recommends their grade!
  • No one ever takes it for more than one semester, it would cost them tuition, but the internships – usually paid ones – go on.
  • Do businesses that hire get to see the reflective report at the end? Not usually.

Example: Parrot, Amanda’s Internship

  • Researched documentation needs of the customer support team
  • Presented on 10 potential projects
  • She did first project from her list, wiki based on Confluence, including development and training
  • They hired her for a 6-month contract to finish and train their staff.

Final notes

  • Try for structured and well-defined internship projects
  • Tech Writing focus usually works well, it can be harder to find structure on the Professional Writing side

Q & A

  • Are most students as strong as Amanda? No, they try to fit the internship to the student, and Amanda was a star.
  • How do they get tech experience? Some have a technical background and then come to the program. Others come from English major background and try to fit into technical side. You can do independent projects and submit them. Or join open-source projects! Can include term papers. IBM has a co-op program.
  • Certificates: Costs about $10K, but they also have Open University access for empty seats, with their own free structure; there are often seats.
  • Terms: There are sponsoring programs and supervisors.
  • Ideal: Paid programs with established offices in SF and some remote work allowed.
  • Difficulty? Students have trouble finding paid internships. Only 7-8 students are looking for an internship each semester, only 2-3 of them have a tech focus. Could tie into a CS internship program.
  • There are still opportunities for the fall.
  • Others: Berkeley has an extension program; Carnegie-Mellon has a campus in Mountain View. UC Santa Cruz has an extension in Santa Clara.

Contact information

Neil Lindeman, Ph.D., Associate Professor at San Francisco State.

1600 Holloway Avenue, HUM 423

San Francisco, CA 94132

Phone: 415-405-0493

Email:lindeman@sfsu.edu

Also: Cal Berkeley will have a job fair in the fall.

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.

Git Demystified for Non-programmers

At the March 2016 meeting, our presenter Jimmy Cuadra gave an introduction to the version control system Git. He described the key concepts behind Git and cleared up common misconceptions. This meeting was summarized by Juan Lara.

What is Git? Git is a distributed version control system that saves the state of files. It’s the version control system most frequently encountered in new projects. Projects do not always use the “distributed” functionality of Git.
Why should writers care about Git? Git is the lingua franca of many developers. Also, Git is increasingly being used outside of software development. For example, you can use Git Hub Pages to run a blog.
What is a Git Blob? Git tracks the contents of a file and not the file itself. All content is stored in a Blob object.
 
What is a Git Tree? A git tree keeps track of the hierarchy of a repository. It can contain Git blobs or other git trees.
What is the Commit command? The Commit command creates a Git Commit which is a snapshot of files frozen in time. The command creates a tree of blobs using an ID and meta-data. The ID maps to the content in the blobs. One important concept to understand is that the ID directly maps to the contents of a file. Meta-data includes time, person creating the commit, and a commit message.
What is a Git Repository? A Git repository is a database of Git objects including a history of every commit.
What is a Git Branch? A branch is a named Commit. It’s the flagship feature of Git and developers love to branch all over the place. Branches allow you to work on a crazy idea without breaking the main project branch.

Networking for Introverts

The San Francisco chapter’s April 2015 meeting featured Rebecca Firestone, an award-winning technical writer, content developer, and trainer with 20 years of experience in startup and corporate environments. This meeting was summarized by Laurie Bouck.

——————–

Most technical writers are introverts, yet the job search process, with its emphasis on networking, seems to reward extroverts. How can those of us at the quieter end of the personality spectrum be effective at networking, a key career-building skill? At the April STC meeting, senior technical writer Rebecca Firestone explained how introverts can network in ways that work for them.

Introverts recharge through solitude; seek peace, sanctuary, and beauty; and have an active inner life. They also can be successful leaders; famous introverts include Abraham Lincoln, Bill Gates, and Barack Obama. Extroverts, on the other hand, thrive around other people and prefer to work in groups, which Firestone pointed out sounds like a contemporary job description.

Networking to Fit Your Personality

For introverts, Firestone said, networking can feel phony, especially when we’re told that networking is easy and we just need to “lean in.” Networking does not involve asking strangers for a job or following any networking book too literally. Instead, we need to recognize that networking takes time, like cultivating a garden. When approached this way, Firestone said, networking is intrinsically rewarding.

To network successfully as an introvert, Firestone recommends the following:

  • Interact with each person you meet as if that person might be important to your success—like a little sprout in the garden that might thrive.
  • Look for opportunities to talk and network with people you already know, such as friends and colleagues at meetings of professional organizations.
  • Think about one to three topics or activities that interest you this week, and use these ideas to start conversations with others at events.
  • Ask your colleagues what was your “secret sauce” that helped you shine in your work. Use these stories to tell others about yourself in a natural way.
  • Use a little social lubricant, such as a glass of wine, if it helps you relax at events (just don’t overdo it!).
  • Avoid being calculating, too self-promoting, or badgering people when networking (think of how off-putting these behaviors are in a singles bar!).

Networking is a lot like fishing, said Firestone. It takes patience. You must set multiple lines to catch something. When the line wiggles, respond immediately, but keep your cool and don’t overwhelm people—stay calm. Let the person come to you.

Make networking a regular practice. Like dating or house-hunting, Firestone explained, as you network you will realize that there is an abundance of opportunity. Good networking resources include professional associations, alumni associations, and previous employers and colleagues. You can also connect with others by sending holiday and birthday greetings to catch up with people, and writing high quality blog posts to showcase yourself and your skills.

Managing Obstacles to Networking

Firestone said that it’s important to recognize common obstacles to successful networking and develop ways to overcome them. These obstacles, and their work-arounds, include:

  • Desperation: To avoid reaching this point, plan ahead and don’t wait until your hour of need to start networking.
  • Anxiety: To manage anxiety, prepare for networking opportunities, such as bringing index cards with icebreaker topics written on them to review before you go to an event. In general, try to avoid feeling anxious about the job search, so that (for example) you don’t feel crushed if you don’t get the first job you interview for.
  • Fear of looking foolish: To manage fear, remind yourself that everyone else is worried about how they are perceived, too. They don’t notice your fear as much as you think.
  • Inertia: To overcome inertia, start small, with a low-stress person or event.
  • Despair that you’ll always be bad at networking: To counteract despair, rejoice in small networking successes.

Making Networking Fun and Meaningful

The job hunt is easier if you have fun doing it, Firestone said. For example, use a software tool to create a silly or fun project. You can use the project as a writing sample, and it also showcases your personality.

Take the time to learn about something you’re curious about that has some connection to your work. Your interests can help you connect with others in a meaningful way and can expand your career opportunities. Be open to the fact that one thing can lead to another.

Look for people who are applying the topics you are learning about (not experts who are promoting themselves), and ask them about their work. Most of them will be happy that you are interested in their area of expertise.

Try to give rather than take in order to optimize networking, Firestone said. Volunteer for STC, or mentor others, and be generous with your time. Respond quickly and courteously when you are asked to do something. Do meaningful favors for people and provide relevant referrals. The success of others is your success too, and it will build your confidence.

Remember that life paths do not always go in a straight line, Firestone said. Even successful people make big mistakes but still succeed, so be kind to yourself.

 

About the Speaker

Rebecca Firestone started as a technical writer in 1988. Since then, she’s worked in telecom, customer relationship management, architecture, clean energy, and software training. In her most recent role, Rebecca expanded her scope from pure writing to include strategic planning and workload scheduling, learning on the job by trial and error. Most recently, she just completed a stint as a Senior Technical Writer at SolarCity Corporation’s product development office in San Rafael, CA.

 

About this Review’s Author

Laurie Bouck has worked as a writer and editor for over 20 years, covering health topics and consumer technology for clients such as Blue Cross/Blue Shield, McGraw-Hill Online, Alpha Books/Penguin, and CNET. She moved over to technical writing and project management in 2012, and worked most recently at Pacific Gas & Electric Company, revising maintenance and repair documents used in the field.

How to Make Version Control System a Technical Writer’s Best Friend

The February 2016 meeting featured Richard Mateosian, who discussed version control systems. This meeting summary was written by Calvin Yee.

As technical writers, you will encounter version control systems (VCS). If you’re anything like me, a VCS can be confusing and challenging to use. At the February 2016 STC-SF chapter meeting, our speaker, Richard Mateosian, demystified how a VCS works and how using it well help you be a better member of a software development team.

Mr. Mateosian said that there are parallels between what technical writers and developers do when creating a software product. For example:

  • Developers build software components and writers create topics.
  • Developers build the software so it can be tested and writers build documents so they can be reviewed.

Because the processes are similar, any tools that developers and writers can share for creating the product is a good thing.

One of these tools that’s shared is a VCS repository (“repo”). A repo mainly handles text files. Developers handle files that contain code while writers handle files that contain topics or mapping information.

How a Repo Works

A repo provides the following features that are crucial to developing complex software:

  • Keeps track of current and older versions of your files.
  • Keeps track of related files for a project. This is generally the source files for building software packages or documents.
  • Allows for the creation of a Master repo and branches within a repo to manage the complexity of a development project.
  • Includes tools for manipulating files such as checking files in and out, merging files, comparing file versions and keeping a log of changes.
  • Integrates with other tools.
    NOTE: Repos handle text files the best (for diffs and merges), but they don’t handle non-text files as well (such as binary objects, or proprietary files like FrameMaker) nor do they understand the contents of a file nor do they perform component content management (CCM).

Using a Repo

The basic workflow steps for using a repo are:

  1. Maintain a local copy of the repo on your machine.
  2. Keep the local copy in sync with the master repo.
  3. Make your changes and test them locally.
  4. Commit the changes from the local copy of the repo to the master repo.
    NOTE: Committing a file to a repo is a formal way to get the files into the build system to create the software product.

Types of Repos

A VCS repo is either centralized or distributed. The differences are:

  • To use a centralized VCS, you must be connected to the central server to be able to do anything with a file. (Perforce is an example of a centralized VCS.)
  • To use a distributed VCS, you do not need to be connected to the central server (or “master repository”) to make changes to a file. The reason is for a distributed VCS, you are working on a complete copy of the master repository that you downloaded on your local machine. Thus, you can make all the changes you want to a file, create a branch, and so forth without having to be connected to a centralized server. (Git is an example of a distributed VCS. In Git, making a complete copy of a master repo is called “cloning the repo”.)

Features of a Repo

There are three main features that a repo provides:

1. Locking Files

Repos have a locking mechanism to restrict access to a file while it is worked on. The locking mechanism prevents someone else from overwriting your changes or yourself overwriting someone else’s changes in the same file. Repos offer two types of locking mechanisms:

  • Pessimistic locking – You check out a file, which then locks out all other users from editing it. Once you’ve made your changes and check the file back in, then another person can check it out. The assumption is “nothing good will happen if more than one person works on a file at a time”. Subversion and Perforce use this type of locking.
  • Optimistic locking – You check out a file and tells others that you’re working on it without locking it. The assumption is that most changes don’t interfere with each other. Git uses this type of locking.

2. Creating a Branch

To allow for different parts of the software to be developed in parallel, a repo allows you to create branches. This allows different users to work on their part without stepping on other’s work.

This is the workflow for creating a branch in Git:

  1. Create a branch & track it on the “origin” repo.
    NOTE: The term “origin” refers to the location where you made a copy of the source repository.
  2. Make and test changes locally.
  3. Sync the local repo with the origin repo and issue a pull request.
  4. Submitter and reviewers discuss the changes until everyone says LGTM (“looks good to me”).
  5. An authorized user (could be you) merges your branch into the master (the origin repository).
  6. You delete your branch.

Users like Git because it’s easy to create a branch with relatively low overhead (compared to a system like Perforce). In Git, you can think of a branch as a list of pointers. Because you are working with a local copy of a repository, you can do endless pulls from the master repo. This makes it easier to merge the changes back into the master repo.

The main difference between Git and GitHub is that Git is strictly a VCS and GitHub is a website that houses multitudes of projects.

NOTE: A “pull request” is a GitHub-specific review mechanism. It is a way to get reviewers to look at the code or file before it is merged into the master repo. (Reviewers typically receive an email notification of the pull request.)

TIP: To view all the branches for a Git repo, use “git branch”.

3. Performing Merges

When you want to bring the different branches together, you perform a merge. Merging is about putting changes from a branch back into a master copy. The workflow for merging is:

  1. Check out the file.
  2. Make changes.
  3. Check it in.
  4. If the VCS sees a conflict, use its tools to resolve it. The tools let you see both persons’ changes.

Some participants offered their observations about handling merge conflicts:

  • Ask other users roll back their changes so that only the correct changes go through.
  • Ask another human to review a merge conflict. The VCS may not always be correct when it generates a merge conflict. For example, if a user checked out a file but never checked it back in, this can generate a merge conflict.
  • Communicate with your co-workers to coordinate the changes made in a file to minimize merge conflicts.

Other Helpful Tools for the Developer Environment

DITA

If your company wants to implement a DITA system but does not have the budget to implement it, there are options to implement a smaller DITA-compliant system. The “bare bones” for this system are:

  • oXygenXML for editing and publishing (this is a “paid” tool that is DITA-aware). This tool keeps track of the DITA maps.
  • Jenkins (formerly called “Hudson” because Oracle trademarked this name) for automating the build process. Jenkins is a Java-based tool.
  • Git for managing content and version control.
  • DITA Open Toolkit for generating the documentation output.

Source: Eliot Kimber, DITA for Practitioners

Issue Trackers

Because creating software is a complex endeavor, you need to track issues to keep the product development on schedule. Issue trackers can be specialized such as ZenDesk for support tracking. JIRA or Bugzilla for developer-issue tracking. However, all these tools share the same capabilities, which is the ability to track tasks, defects and comments about them.

This is the issue tracking workflow:

  • Someone reports an issue.
  • People Comment.
  • Assign issue to someone.
  • Make changes and others review and comment.
  • Designated reviewer closes the issue.

Summary

Mr. Mateosian emphasized that using the software development tools is not enough by itself. To become a more effective member of the development team, he offered the following tips:

  • Be an active part of the team!
  • Understand the process you’re a part of (you must make yourself a part of it—even if you don’t feel like it!)
  • Be an active participant in all the communication spaces (chat, email, Slack—which is another chat mechanism where you set up a group so everyone can communicate in one place).
  • Take charge of documentation review—make it efficient. The bottom line is don’t waste the developer’s time.

About the Speaker

Richard Mateosian is a fellow of STC and has extensive experience as programmer. His road to becoming an API technical writer was a very winding road. He began as a mathematician, then became a developer, followed by a technical marketer, before becoming an API technical writer. If you have further questions or comments for Richard, you can reach him at xrmxrm@gmail.com.

Link to the slides from Richard’s presentation.