Advent of Technical Writing: Deprecating Content | James' Coffee Blog
jamesg.blog
This is the tenth post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.
  • ryan
    14•5 months ago

    Re: this section:

    As a technical writer, you should stay close to the teams whose work you are documenting. Listen out for any code, SDK, or product changes that may require action. When you hear that a tool may be deprecated, start communicating.

    It just assumes that nobody will ever proactively reach out to the technical writer about deprecations, which is entirely true in practice, but just feels so sad to acknowledge. Please keep your content and document management team(s) in the loop!

    • Semi-Hemi-Demigod
      4•5 months ago

      I think engineers and UX should write the documentation first and then start working on the project. That way you have a clear idea of what should be in the software and how it should look. When things change you update the documentation. Then it’s already done and complete when you release.

  • @hersh@literature.cafeEnglish
    4•5 months ago

    I wish Apple followed these rules. So many deprecations in their man pages and developer documentation have no details at all. No idea what the supposed replacement is. No idea of the underlying reasons. No idea when it will cease to function.

    This is why I still see “launchctl load” everywhere. It’s been deprecated for years, but the replacements are overcomplicated and not clearly communicated in official docs. When Apple finally pulls the plug, so much shit out there is going to break.

    When they deprecated python2, they withheld implementation details and any timeline. Then they finally axed it in a freaking minor point release, without even replacing it with python3. AAAAAAH