Revision as of 14:14, September 16, 2019 by Chrissyforrest (talk | contribs) (→‎Writing)
Jump to: navigation, search

Quickstart Guide for New Hires

Welcome to the Tech Pubs team! We're excited to have you. If you have not done so already, check out our welcome video:

Welcome to Genesys Technical Publications

Almost everything you need to know as a technical writer at Genesys is available by clicking on the table of contents links to your left. This Writer's Guide is a collaborative exercise in having a consistent approach to writing documentation here at Genesys. If you think something's missing, by the way, please work to add it!

If you're ready to dive in, before getting into the details of writing at Genesys (those links on the left), you might want to check out the resources available from the pages below. Happy onboarding!

People

People you should follow in Confluence (our intranet tool):

  • Technical Publications: Our department falls under the Chief Technology Organization. R&D is a subsection of that, to which Tech Pubs belongs.
  • Michael Katten - Director, Technical Publications;
  • Slava Zhakov - Chief Technology Officer
  • Tony Bates - Chief Executive Officer
  • Peter Graf - Chief Product Officer
  • Tech Pubs Blog. - Part of the Chief Technology Organization
    And you should set up your own profile in Confluence so that people can learn a bit about you.
  • Need to know the details of a project? Take a look at the Who's Who for PMs, PjMs and Writers - On- Premises and Cloud. This page lists the Product Managers (PMs) and Project Managers (PjMs) who are partnered with us on various projects. It's updated by our writers when they remember to do it.
  • Still need help? Our contacts page has a list of who you need, when you need it.

Writing

Working with the wiki

  • Watch and read through the following training materials provided to Customer Care in 2016/2017:
    Note: Clicking the link takes you to the location in which it is stored in the Box Technical Publications site.
  • Navigate through the Wiki Structure help section to see how you should be putting your content together.
  • What's the wiki approval process? Find out here.
  • Wondering how to format text? Take a look at our Typography page.
  • So you already published your content but now you need to change it? No worries, we've got you covered: Updating Published Content.
  • Learn how to publish your content.
  • Need help with wiki markup? See this URL: Wiki Format

Cloud content

Releases

  • You might be thinking, but what documents go where?! Don't worry, we've got you covered and we even talk about release types!

Release Notes

JIRA

  • To help us work more closely with our engineering team and track our progress during efficiently, our teams use JIRA. JIRA is a issue tracking product that, like Confluence, has been developed by Atlassian. It provides bug tracking, issue tracking, and project management functions.
  • Here's are some links to training materials about JIRA:
    • JIRA 101: Here's the video and the associated PowerPoint used as part of training when we moved to JIRA as our bug tracking system.
    • JIRA FAQ created by Project Management Office (PMO) and geared towards them.

Other software, tools, and applications

  • Confluence:
  • Other software
    • For Canadian writers, look to :\\absolut\techpubs\software.
    • For U.S. writers, look to \\galaxy\genesys\Techpubs7\G\Acrobat_9 for Adobe Acrobat 9 Pro Extended.
    • For Chennai writers, check with Jaba or the manager to whom you report.
    • For France, UK, and Israel writers, check with the manager to whom you report.

Other resources

  • For all the CTO happenings in our organization check out the regularly updated CTO Home Page. CTO, or the Chief Technology Office, is the department we exist within. Our department reports to Slava Zhakov, the Chief Technology Officer.
  • How do you set up Go-to-meeting?
  • And if you just feel like exploring, here's a good place to start.

Writing for Customers

When writing customer documentation, we write according to our customers' needs - in other words, what they are looking for.

Some things to consider:

  • Your content should be written to answer a customer's business need. For example, an administrator is looking for how to set up an agent to handle calls, email, chat, and so forth. Another example would be an agent simply looking for information on how to login and start taking calls. And a third might be a supervisor wanting to know how to generate a report in the Cloud. Here's a link to articles that follow this model.
  • Customers can arrive on your page from anywhere, including from a search. Therefore, it's important to provide context at the beginning of the content so that the reader knows if this content contains what they're looking for, or if they need to continue searching.
  • When reviewing JIRA issues for documentation needs:
    • A software change could impact something that the customer has already set up. Did the Developers replace an existing feature with a new feature that handles that functionality? Does the new version support the old approach and, if so, is there anything the customer needs to be alerted about?
    • Does the JIRA item mention something about options or a new option being needed? Does it talk about configuration that might require documentation additions?
    • Review any text that might require something the customer needs to know about. Think from the perspective of the user. Developers don't always think like the user, or may not write their comments in a way that clearly explains the impact of a change on the user.

How to Work with Subject Matter Experts

Subject Matter Experts can be anyone in Genesys, including Developers, QA people, Product Managers, Project Managers, Customer Care people, Offer Leads (Cloud offerings), Operations people (Cloud offerings) and others. On a daily basis, you will work most regularly with Developers, QA people, and Product Managers. In any release (whether using Waterfall, Agile, or Continuous Delivery/Continuous Integration models), you especially rely on them to create your product content, including release notes.

Here are some guidelines or tips in working with SMEs.

  • Learn your product by using the user interface, accessing a version of it on a demo image, reading product documentation, and the like. This not only helps you write product content but enables you to make the best use of the time you have with subject matter experts.
  • Create a relationship with them by learning about their work, their day-to-day tasks, challenges and needs, and sharing with them the same. This builds an understanding between you and creates empathy, especially when workloads are high and schedules are tight.
  • Ask them what the best way is to communicate with them: by email, phone call, JIRA comment, TOI, or a face-to-face meeting if you are co-located. This shows them that you are willing to work with them.
  • When you interact with them, be prepared with the questions or issues prior to that interaction to make best use of your time and theirs.
  • Interact professionally with them. Express appreciation for their work and their responses.
  • When creating document review schedules, take into account their personal work schedule. For example, is it possible to schedule reviews during a period when their workload is lightest? Admittedly, that may be challenging, especially for Continuous Delivery projects. So, do your best.
  • If you know that giving a little more will result in them making more time for you, do it as long as it's reasonable. In the past, when our output files were PDF or CHMs (before online), reviewers occasionally asked to be provided with documents in Word. Since there was no easy way to do that, we usually declined because we didn't want to set a precedent and add overhead. So, use common sense.
  • Be willing to help them when they need help, if that's possible. That will make them more willing to help you.
  • Remember that you all belong to a team that is working towards the same goal. Documentation is part of the product, not an add on. Sometimes new employees, even those from a recently acquired company, don't understand the role of customer documentation, the needs of a Tech Pubs writer, and the requirements of SMEs with respect to documentation reviews and content information. It's up to you to train them about it.
  • Be a QA person in the way you investigate how to document a feature or issue. As writers, you know that we don't just take text that a Developer, QA or another person provides, not only because they may or may not be a good writer but because they don't always understand the nuance of saying something one way versus another. For example some text provided may be ambiguous. You'll need to dig a little to find out exactly what the situation is so that you can clearly explain it to customers.

Tips for Dealing with Time Zones

Genesys is a global company. As such, you may be working with Genesys folks situated in time zones different from the one in which you are located. Here are some tips for handling this.

  • If the people are part of your product team:
    • Consider whether you can change your working hours to better overlap their working hours. For example, if they are 4 hours earlier or 3 hours later, can you shift your working schedule to have some overlap? You are not expected to work longer hours to accommodate their time zone or their schedule. Granted, there may be emergencies that require that but it should not be a regular occurrence. If it is, work with your manager to determine how best to handle the situation and present it to your team.
    • For team meetings, make sure they are scheduled during a period when you are working. If the time difference makes that almost impossible, consider only occasionally attending and inform your team accordingly.
    • For one-on-one meetings, like TOIs, phone calls, and so forth, just compare schedules and come up with a mutual day and time that will work for all participants.
    • For meetings you can't attend, ask the person who set up the meeting to record the call so you can listen to it when you are available.
  • If the people are not part of your product team but are people from whom you do need answers, expect that responses from them may be delayed. So, plan accordingly.


And remember if you have any questions, feel free to email any of your new teammates! We're here to help and would be happy to do so. Welcome to Genesys!

Comments or questions about this documentation? Contact us for support!