Gracious speech is like clover honey —
Good taste to the soul, quick energy for the body.
-Proverbs 16:24

I have to celebrate this occasion: I started at work January 23. Yesterday, April 7, we published my first release notes, written entirely from scratch by me. This is a big deal because release notes are one of the projects we have with a hard and fast deadline, and they can be a lot of work.

Many companies’ release notes look like this:

  1. Add new wizz to the existing functionality.
  2. Improve gadget to expand functionality.
  3. New feature: doohickey now lets you do another thing.

    And that’s pretty much it. Easy enough to pound out in an hour.

     Our release notes, on the other hand, are fairly detailed documents that include a compelling “sell” of the feature followed by screenshots and a brief description of how to use it/where to find it. To write a release note for one user story, I:

    1. Review the technical specifications, which describe how the feature should work.
    2. Go into the test product environment and try out the new feature, playing around until I have an idea of how it works.
    3. Write an outline of why and how, along with questions for the PM.
    4. Meet with the PMs individually and review all their features, ask questions, understand the feature.
    5. Write a draft of the release notes and send it to the PM to ensure it accurately reflects how the feature works. Lots of screenshots, lots of “I have a quick question.”
    6. Write more, edit more. Repeat several times.
    7. Find out the are several new stories I didn’t know about and the release notes draft is due in two days!
    8. Send out draft for review by entire technical team and upper management. Don’t sleep that night at all.
    9. Over the next week, get comments back. Hound PMs for comments on their stories and incorporate changes. Pray I didn’t make any technical errors.
    10. Receive copy edits from other writers and incorporate edits.
    11. Publish release notes to production about 5 pm and stay late at work to check everything went out correctly.
    12. WHEW! Now all I have to do is update the Help Center content with the actual new information in the next two weeks. That has to be done before the release, which is always two weeks after these notes go out.

    As you can imagine, after all this, these notes get pretty comprehensive. I’ve seen times when release note content served as the verbatim foundation for the Help Center topic.

    This was my first release writing the notes entirely on my own, and I had 13 stories to master before writing. My boss warned me that I might get overwhelmed and if I needed him to pick up some of the work, he could step in. I told him I thought I could handle it, and I’m glad I have it a shot, because now I did the entire thing on my own and I feel really proud of myself!

    Now I have two weeks of crunch time updating Help Center and trying to finish up another project I’ve been writing on the side. I may be offline for done of that time.

    I made lemon bars with Meyer lemons to celebrate. I would have liked lemon meringue pie, but alas, didn’t have time to make one. But I’ll take lemon bars and the sweet, sweet taste of success.

    Leave a Reply

    Your email address will not be published.