3

I am writing the release documentation for a software product and a design flaw has been discovered after the code has been frozen. Does the documentation describing this issue change if the product is a beta release to selected customers only? What if the product is a 1.0 to be exposed to a public audience? What if no software patch is currently scheduled?

Related to How should I document a product release with an inherently flawed design?

Jason Fox
  • 477
  • 2
  • 13

2 Answers2

3

Beta or not does not matter, whether a patch exists does not matter, write it up. Document it.

Like your previous question, this is a business matter, not a documentation issue you should decide for yourself. You should document it, even if you have just ONE beta tester, whether or not a patch exists, and let your management decide if they are willing to risk any liability or negative publicity that may arise from a failure to document the behavior.

This should not be your decision, it should be the decision of somebody with fiscal responsibility for the fate of your company or employer.

Amadeus
  • 107,252
  • 9
  • 137
  • 352
3

Although in most cases the choice rests with business decision makers and those in charge of message tone, it's reasonable for the writer to have some proposed solutions. Choices may vary based on:

  • Potential liability/negative publicity.
  • Schedule of product releases vs documentation releases, that is, how much time after code freeze/flaw finding do you have before doc freeze, does doc really "freeze" or can it be updated easily, how does the doc staff availability affect the ability to be responsive, etc.

A few suggestions around your scenarios:

  • If the flaw appears in beta for a limited audience and will be fixed by GA:

    • A release note and workaround (if applicable) should be sufficient. If the workaround is too complex/lengthy for release notes, it can be standalone as a knowledge base article (available to just the beta participants as appropriate).
    • But proceed with the core documentation as if the fix will be in GA as anticipated. If you're publishing the core doc for the beta users, make sure it's tagged as beta -- use it as an opportunity to elicit feedback as well as to notify users that it's not quite ready for prime time.

  • If the flaw is exposed to the public and does not have a scheduled fix, then it's part of the product and needs to be documented as such.

  • If the flaw is discovered too late for the core documentation release, release notes plus KB article and maybe more direct outreach to the customer base.
  • If the flaw is really crippling, the doc staff can speak up for the users and say we can't release like this, and see if there are other options to get a fix happening or a software-based workaround (like disabling part of the interface so the customer can't get into trouble with the flaw).
Sharon M
  • 738
  • 5
  • 11