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.

Book Review: DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, by Laura Bellamy et al

Reviewed by Richard Mateosian

In the Mar/Apr 2012 Micro Review, I reviewed the IBM Style Guide. This book is a companion to that style guide. It focuses on the Darwin Information Typing Architecture (DITA), an XML-based system for authoring and publishing technical information. Originally an IBM project, DITA is now an open-source toolkit, managed by the independent global consortium Organization for Advancement of Structured Information Standards (OASIS).

DITA provides a technical infrastructure for topic-based writing and publishing. Following a model that evolved from the online-help systems of the 1990s, DITA starts with the idea that most technical documentation can be broken into chunks, and that each chunk falls into one of the following basic categories: procedures, concepts, and reference. The Darwin part of the name comes from DITA’s use of inheritance to allow different projects to extend and specialize the basic categories. Unlike DocBook, another popular XML schema for technical publishing, DITA has an associated set of tools for building an automated process that supports publishing multiple documents to multiple output media from a single database of content.

This book provides a clear treatment of metadata and DITA maps. Metadata — data about the content — provides one key to achieving DITA’s benefits. Properly designing and using metadata makes your content easy for you to manage and for your users to find, and it helps you provide different output to different audiences. While much of the DITA metadata stays with the content, a significant portion of it can reside in DITA maps — structures that define documents in terms of the topics that comprise them and the relationships among those topics. Becoming thoroughly familiar with DITA maps is an important step on the road to feeling comfortable with DITA.

Understanding DITA, especially its architectural aspects, entails digging into the details. DITA is conceptually simple but the details are hard for most people to wrap their minds around. This book helps you understand the details and, by laying out best practices, makes a lot of choices for you, simplifying your task of getting up to speed. The authors are aware of the learning difficulties DITA presents for many users. For example, they begin the chapter on metadata by saying, “If your writing team is just learning about DITA elements, don’t scare them by using fancy words such as metadata at team meetings. Otherwise the guy who brings the donuts might not come anymore.”

If you’re looking for an alternative method for delivering your online Help, or are just interested in pushing the limits with EPUB, this presentation is for you.

Like the IBM Style Guide, this book is sure to become a standard. If you want to work in DITA, you need this book. If you’re not sure you want to work in DITA — it’s overkill for many applications, though new tools and techniques keep lowering the bar — the detailed information in this book will give you a basis for deciding.

DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA by Laura Bellamy et al (IBM Press/Pearson, Upper Saddle River NJ, 2012, 296pp, ISBN 978-0-13-248052-9, www.ibmpressbooks.com, $42.99)

Software Review: MadCap Flare 9 has Much to Offer

by Patrick Lufkin

The technical communication environment continues to grow ever more challenging. Markets and target audiences are truly global. Users expect content to be delivered on a daunting array of platforms using different technologies and screen sizes. Users want both online delivery–web-pages, links, videos–but also PDFs they can print. Users grown accustomed to social media increasingly expect to be able to question and comment on your online content. And worse, if you’ve been around for a while, you probably have a large cache of legacy documents in outdated formats that don’t quite fit into the evolving scene.

If the forgoing sounds familiar, you may want to take a good hard look at the latest release of MadCap Flare.

First released in 2006, Flare has matured into a robust and versatile authoring platform for just about anything you would want to produce for online or print.

Flare 9 offers a number of enhancements that I want to touch on, but first, for those who aren’t familiar with Flare, I would like to describe the basic product.

Flare is a single-sourcing, topic-based authoring platform, which uses XML markup for maximum flexibility. Using Flare, you can store and manage all of your content in one place, and then output as many variants as you need, in as many formats as you need. For example, you could produce two versions of a workbook, a student’s version showing only the problems, and an instructor’s version with the answers filled in. Or you could produce several versions of an employee handbook, one for display on a desktop computer, one for use in a class, and others optimized for small-screen mobile devices used by employees in the field.

For those used to authoring in Word or FrameMaker, Flare may take a little getting used to because it works best using a different mindset and a different workflow. Instead of writing a long document with embedded formatting, you produce a collection of topics, each in its own file. The topics aren’t the final output, but serve as the source from which a wide variety of final outputs may be drawn. When it comes time to generate output, Flare gathers the needed content from the various files, sequences it, applies formatting, and makes it compatible with specific devices using output definitions called targets.

Everything you need to produce various outputs—content files, templates, master pages, style sheets, and so on—is held, organized, and managed as a Flare Project. Flare comes with an array of well-designed project elements, which you can use, modify, or replace as needed. Flare provides a wizard that will create a project for you, selecting elements based on your needs. If you have existing content, you can convert it into a Flare project using tools and filters built into Flare. Flare can import from Word, FrameMaker, DITA, and many online help formats.

For entering content, Flare provides both an XML editor and a WYSIWYG text editor. In Flare 9, both editors are fully integrated so that changes made in one are immediately reflected in the other. Most authors will choose to work in the WYSIWYG text editor because you do not need to know anything about XML to use it. In either case, files are stored as standards-compliant XML.

Flare includes a full complement of tools and features to make your job easier–dictionaries, spell checkers, table and equation editors, tools for inserting special characters and symbols, and more. You can store text that will often be reused, such as warnings and legal boilerplate, in snippets, and store text liable to change, such as product names and versions, in variables. Flare also has tools for managing the reviewing process, and for tracking project progress, generating reports, and locating possible problems such as broken links.

Over the years MadCap has responded well to the needs of its users so the core product is already well designed. Still Flare 9 offers a number of attractive enhancements. A few of the enhancements should be appreciated by everyone; others are aimed at users with specialized needs. In the first category, Flare is now bundled with Capture, MadCap’s screen capture utility. Prior to Flare 9, Capture was only available as a separate product. In the second category, Flare now offers extensive support for right-to-left languages such as Arabic. Not everyone needs this capability, but those who do will find it hard to obtain elsewhere.

Among other enhancements, Flare 9 now includes:

  • A new version of the equation editor.
  • Enhanced support for print output-including CMYK ink support-enabling the production of high-quality, full-color, press-printed documents.
  • Enhanced support for HTML 5 and CSS 3.
  • Enhanced ability to use complex conditional expression for including or excluding content, including the use of Boolean expressions.
  • EPub output has been upgraded to support EPub 3, and now also supports MOBI output to be viewed on a Kindle.
  • Enhanced support for socially enabled output through a new product called MadCap Pulse.

More in-depth coverage of the new features can be found in Mathew Ellison’s article in the March, 2013, issue of Intercom (requires log in to access).

Patrick Lufkin is a past-president of the San Francisco chapter, and a book reviewer for the STC Journal, Technical Communication. He is Co-chair of Touchstone, the Northern California technical communication competition, and Chair of the Kenneth M. Gordon Scholarship for Technical Communication.