10 Quick Tips for Project Managers about Help Content

10 Tips for Help Content

10 tips for PMs about help content

As a follow-up to my last post, When Help Content Is Forgotten, my colleague pointed out that having a set of agreed-upon best practices for technical writers is one of the first steps in establishing traction with project managers. Otherwise, project managers can resist or dismiss a technical writer’s recommendations as subjective opinion.

In an effort to be concise, here’s my stab at the ten things project managers should know when working with technical writers. Imagine formatting these ten sentences in a neat little card that you periodically email to project managers, or that you give project managers when meeting them for the first time. I made them concise so that they’ll be read. These are the 10 concepts that all project managers should know about help content.

10 Best Practices for Help Content

  1. Allocate budget for help content in your project plan.
  2. After your project is approved, contact a technical writer about deadlines for deliverables.
  3. Recognize that what seems intuitive to you may be unintuitive to users.
  4. Technical writers need access to test environments, prototypes, and dummy data.
  5. The user interface is driven by text, so involve a technical writer’s language expertise with prototypes.
  6. Because help content is part of the user experience, technical writers work closely with interaction designers.
  7. Expect short guides and visual content rather than long manuals.
  8. If collaboration and distributed ownership are important, consider a wiki platform.
  9. Technical writers are your application’s first users — their feedback can improve usability.
  10. Documentation isn’t finished with the application’s release, but continues as users submit feedback.

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

10 thoughts on “10 Quick Tips for Project Managers about Help Content

  1. Larry Kunz

    Good list. There’s nothing here with which I disagree, and I can’t think of anything big that you’ve left off.

    You might make an even stronger case if you organize these into three groups:

    What technical writers contribute to the project: #3, 5, 7, 9, 10 (and reword #7 to something like “Technical writers can select the right media for the job: short guides and visual content are often better than long manuals.”)

    What technical writers need to do their jobs: #4, 6, 8

    And because of all this, what the project plan has to contain: #1, 2

  2. Sarah Maddox

    Hallo Tom

    Great idea! A useful list for both product managers and technical writers.

    I agree with Larry about rewording point 7. Maybe even change the “and” to an “or” because visual content isn’t always useful.

    It may be worth rewording point 2. It currently says:
    “After your project is approved, contact a technical writer about deadlines for deliverables.”
    Instead, I think the PM should consult the tech writer much earlier and include the tech writer’s estimates for documentation deliverables in the project plan and costing.

    Cheers, Sarah

    1. Mel (Melanie)

      Sarah – I really like your last paragraph! It’s so much fun to have a Product Mgr. TELL me when the documentation needs be done without thinking to consult me about a reasonable time schedule for completing the documentation!! :()

  3. David

    #1 to #2 read to me as if the PM decided #1 without involving the tech writer until #2.
    The awareness difference can be:
    a) I’ve got $100, give it to Bob, tick a box.
    b) I’ve written a shopping list, I’ve saved $100, and I’ll give them to Bob to bring back delicious fresh fruit and vegetables. I don’t want rotten or bruised items Bob, and know there are seasonal variations in prices due to cyclones and pest plagues that may come up.

    As you are what you eat, your customer experience may result in tasty goodness, or quick to rot trash.

  4. Rengaraman

    Valid points. I would like to ellabarote point #9 as

    9a) Include Technical writer as a part of QA team so that they could access and log their findings using some bug tracking system(like JIRA).


  5. Christine Astle

    I’d suggest combining 7 and 8 into something about listening to the tech writer’s expertise on the best content/structure/delivery format and method (or most realistic if you haven’t included the tech writer until the 11th hour).

    Also, it would be great if this were a general team charter or advertisment used to educate various stakeholders. I think educating the project manager is part of it. However, there are others who need a little education about tech writers, what they do and where they add value.

  6. Chet Kamal Parkash

    Previously I have written many articles about Technical Writing Profession. If this is something that you enjoy doing, it is probably worthwhile that you read this section for improving your skills to stand in this Profession. You have much to learn from the articles that
    are available online and be in touch with the Group of Technical Writers.

    Such a way, you can improve your writing skills and as i always say that it is not a Copy-Paste job and you must be Tech Savvy.

    Always try to look for words that are helpful to sell the Technology. Your words are the helpful tools to keep the communcation on
    right track between the Technology and the Users.

  7. Shweta Hardikar

    I am a regular reader of I’s rather be Writing and have always always found stuff extremely useful in my day to day life. However, by far this is the best list that i have come across. I am a technical writer and currently developing end-user documentation for a product and face all imaginable and unimaginable challeges for a Tech Writer. I keep on telling the team that I am a user of the product and if I face hurdles, trust me that end user will also face some of them…this list is so applicable to my work here. Thanks!


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>