June 2017
By Nicky Bleiel

Image: © alphaspirit/123rf.com

Nicky Bleiel is a Watson Information Developer at IBM. She is a Past President and Associate Fellow of the Society for Technical Communication and has 20 years of experience writing and designing information for software products in the cognitive computing, technical publication, media sales, industrial automation, simulation, and pharmaceutical industries. Nicky is a popular speaker at many conferences and has been published in STC’s Intercom, tcworld magazine, ISTC Communicator, and more.


www.nickybleiel.com


 


 

Three collaboration tools for technical communicators

Are you working in a distributed documentation team? Then consider these software solutions that will make your job easier and facilitate teamwork.

Ten years ago, I gave a talk at the STC Summit called "Cool Tools for Tech Writers for $100 or Less" that featured tools that could be used to automate file backup, create and edit icons, create characters, edit images, take screen captures, remove document metadata, and more. Most of those tools were useful for performing the "solo" tasks of technical communication.

But times are different now, and while we still need the tools I talked about then, in 2017 "cool tools" must include collaboration features for the entire development team, because so many of us work in global teams that are using Agile software development methodologies. Collaboration tools… 


  •  can be accessed from anywhere via the Web,
  • allow synchronous communication, and
  • include social features.

There are a number of collaboration tools for software development teams that can be used separately or in tandem. Among them are GitHub, Slack, and Mural.

  • GitHub is designed for software project management – It is a web-based repository for software projects that includes source control, issue tracking, notifications, documentation, and social features.
  • Slack is used for chat communication – It is used for individual and group messaging.
  • Mural is intended for planning and organizing – It lets team members from around the world collaborate on a virtual whiteboard.

Some of these tools integrate with each other, for example, GitHub and Slack. When researching collaboration tools for your teams, you may want to include the ability to integrate with other tools on your list of requirements.

GitHub

GitHub is a web-based repository for managing software projects and the version control of code. Public GitHub is reportedly the world's largest open-source community, hosting over 35 million repositories that include both code and the documentation for that code. In addition to public projects, GitHub projects can also be private or hosted internally behind your company firewall on GitHub Enterprise.

GitHub could be considered a "one-stop development shop" because it includes version control, project management, and social features. Technical communicators can manage documentation issues (bugs and feature requests) using GitHub’s issue tracking. It makes sense to use GitHub for the version control of your documentation files, as storing documentation files along with code and other project artifacts means that documentation is not siloed; it can follow the same workflow as code, and the project's collaborators can review and contribute to the documentation. This is especially important when your team is using an Agile software process, where docs are part of the "definition of done".

There are three documentation options in GitHub: READMEs, GitHub Pages, and a Wiki. These options can be used strictly to document your team's GitHub projects, or you can use them for team collaboration, information gathering, planning, or whatever your team deems necessary.

GitHub has several social features that make it easy to keep track of other team members and projects. You can "follow" other contributors and GitHub will automatically alert you of their activities. You can also "watch" specific projects, i.e. you will receive notices about these. If you prefer to tag a repository, but skip the notifications, you can "star" (favorite) it. You can then go to your "stars page" to catch up on those projects, as well as take a look at the "stars" of your friends.

Over 100 productivity tools can be integrated with GitHub, which provide additional opportunities for collaboration. You can see the complete list here, but here are a few you and your team might find useful:

  • Atom is an open-source, cross-platform text editor that has GitHub version control built in. You can use it to author documentation in Markdown and AsciiDoc, or to write code.
  • ZenHub lets you view and manage your GitHub issues on a virtual task board, which is great for both Agile and virtual teams.
  • Slack is a team messaging application. GitHub commits, pull requests, and merges can be automatically posted to Slack messaging channels.
  • GitHub Desktop lets you contribute to GitHub projects with a GUI, instead of using command-line Git.
  • GitBook can be used to host, write, and publish documentation collaboratively. Outputs include PDF, ePub, mobile or a website, and you can author in Markdown or AsciiDoc.

Slack

Slack is an instant messaging tool that facilitates team communication by combining group chat with useful tools. Slack is built around the concept of channels. Channels are group chats that anyone can set up and then invite team members to join the conversation. Anyone can read or join any Public channel on your company's Slack, while Private channels are confidential and by invitation only. Because anyone can start a Slack channel, it is easy to start a conversation about any project or topic, which encourages collaboration. And when a channel is no longer needed, it is just as easy to archive it. Traditional chat functions are also available in Slack. You can create small group chats or contact team members via direct message.

In addition to text chat, you can communicate with others on your team by using voice or video call. You can start group calls with the entire team (useful for daily standups) or hold one-on-one calls. Speaking of standups, Agile teams can configure Slackbot, a built-in bot, to remind everyone that it is time for the daily standup. Slackbot will also answer your "how do I?" questions about Slack features with a link to the appropriate topic in the Slack Help Center.

On the practical side, you can share files on Slack, as well as pin and "star" (favorite) messages. Slack messages are archived and searchable (although archiving is limited on the free version), and you can quickly ping a team member on any channel by using an @mention (GitHub also has this feature). Using @channel will ping everyone on that Slack channel as well as via email, while @here will just alert those on the Slack channel. On the fun side, you can include emojis within messages, as well as use them as reactions to messages. And you and your team can create custom emojis. Emojis are one way to make Slack chats more "conversational," but you can also add animated GIFs and video. Giphy, a GIF search engine popular on Twitter and Facebook, can be integrated with Slack.

Slack integrates with over 100 apps in a variety of categories (see https://slack.com/apps/), including GitHub, Twitter, Skype, Kayak, and more. You can also build your own custom integrations using the Slack API. Slack offers both free and paid plans.

Mural

Mural is best described as an online whiteboard that can be used for synchronous team planning. With Mural, teams can add and arrange sticky notes to boards (called "murals") together in real time.

For distributed Agile teams, Mural is a great way to create a Kanban or Scrum board that the entire team can contribute to and reference during daily standups. You could also create a mural for team retrospectives, and have everyone add sticky notes under the three common Agile retrospective questions – "what went well", "what went wrong", "what to improve", and "kudos" – then group the notes and vote on what issues to discuss.

Mural can also be used to develop workflows, personas, or mind maps, and plan projects and organize events or any kind of brainstorming session.

When working synchronously in a mural, team members can chat, add comments on any part of the mural, and vote anonymously to reach group consensus. "Following" a team member while you are working will show you in real time exactly where their focus is in the mural. As not all changes are made with the entire group present, any changes made asynchronously between team meetings can be viewed in the "Activities" sidebar.

You can add images and videos (including YouTube videos) to your murals, as well as links and documents, so your murals can become quite robust and detailed. Mural has a free 30-day trial.

Collaboration beyond tools

GitHub, Slack, and Mural are just three of the many collaboration tools you can evaluate for your team. But no matter which ones you choose, there will still be work to do after the tools are set up. For truly effective collaboration, you need to develop guidelines and best practices to ensure tools are used effectively.

In GitHub, you should consider creating a standard structure for both bug reports and feature requests. You can also create guidelines for the creation of issue labels (note: GitHub includes issue labels for "bugs", "enhancements", and "questions", but not "documentation" – so add that label first).

Slack makes communication easy and fun, but you need to separate the work communication from casual chatting.  Many teams will create a "water cooler" channel for informal conversations.

In Mural, a good best practice is to create a "legend" for planning and workflow boards – for example, the sticky note shapes and colors to use for each category – that everyone can follow when working together.

Of course, the best way to ensure team productivity and success is for the entire project team to work together when evaluating, choosing, and developing best practices for collaboration tools. That will take any tool from useful to "cool".

Additional resources