17

The deadline is looming and someone realizes the product can't be shipped without documentation. Once the product leaves the remit of the software engineers (who obviously only ever write wonderful code) and is passed on to a more objective audience an obvious design flaw is discovered. May be the password is being sent using GET, maybe the so-called REST API is inherently stateful, maybe there is just some kludge which makes loading the data very painful.

Anyway, there is no capacity to change the code to fix the flaw before the deadline. Something must be shipped and documented as-is. The engineering team will have to fix it with a patch in the next version.

What is an effective strategy for documenting such a product? Should the design flaws be highlighted or ignored?

Improve this question
4
  • 10
    Make sure you raise all the hell you can by doing it. Make sure the executives know that you are doing this at their request/ approval.
    – JP Chapleau
    Commented Feb 14, 2018 at 13:26
  • 1
    This seems more like an ethical question about the software development business than a question about technical writing.
    – Philipp
    Commented Feb 14, 2018 at 15:34
  • 8
    @Philipp Understanding such issues (whether you look at them as ethical or business issues) is a large part of the tech writer's job, You need to know how and when to present them and how to execute the business decision that gets made correctly.
    – user16226
    Commented Feb 14, 2018 at 16:00
  • @Philipp I make decisions about this kind of case as a tech writer, so I think it fits. There are different ways to handle this -- known issues, document the flaw right there in the doc, add to a troubleshooting section, describe best practices that conveniently avoid bumping into the problem...
    – Monica Cellio
    Commented Feb 14, 2018 at 16:01

3 Answers 3

Reset to default
19

This is essentially a business problem, which is not to say it is off topic, because technical writers exist to solve business problems. But it is not a problem the writer should try to solve on their own. You have to get guidance from the product manager.

However, there is a very good chance that the product manager has not thought this through, so you may have to go to them an lay out a set of options and their potential consequences:

  1. Document the flaws clearly. Likely consequences: limited adoption. Upsides: avoid disappointing or misleading customers. Hopefully keep them interested in what you are doing for the next release.

  2. Don't mention the flaws at all. Likely consequences: higher initial adoption followed by disappointment and possibly lawsuits when the flaws become apparent. You may turn customers off long term and not have the chance to win them back once the fixed version is released. Alternatively, you may survive the initial disappointment and ride the first mover advantage to a home run with the second release.

  3. Document around the flaws. That is, write up procedures that work around the design flaws. Likely consequences: The product may appear weirdly designed or over complicated on first release, which may not matter if it has unique functionality that people want. Second version can then be sold as a significant upgrade with improved ease of use. However, the time to develop, test, and document the workarounds could delay the release.

Option three is way more common than most people may suspect.

Improve this answer
3
  • #3: It's not a bug, it's a feature! ;)
    – Joe
    Commented Feb 21, 2018 at 2:41
  • +1 for this: "But it is not a problem the writer should try to solve on their own. You have to get guidance from the product manager." But more than guidance. Someone other than a doc writer typically needs to decide what the message is for users: Is this intended (design) and something we want to tell users? Is it unintended and should be fixed (bug)? Is it something we acknowledge internally (bug or design) but that we don't want to proclaim? There are multiple possibilities, but it is rarely appropriate for a doc writer to be the decider about the right message to send in this regard.
    – Drew
    Commented Dec 31, 2018 at 17:24
  • Typically technical doc (other than release notes and such) does not document bugs and bug workarounds. It's generally up to product mgt & development to decide whether something is a bug or by design. And that's a question of intention, above all.
    – Drew
    Commented Dec 31, 2018 at 17:25
10

Absolutely document them and point them out to management.

As Mark says, this is a business problem. As a coder myself with forty years of commercial experience, your problem is that almost any flaw can be exploited to the detriment and possible losses of your clients, such a password sent using GET.

Despite license agreements that disclaim any and all responsibility for such losses, lawsuits can still happen and may cost a fortune to defend and/or settle, and even worse, publicity if such a thing happens and it is clear your company knew of it can be devastating to your company's reputation, reliability, and sales. If your company cannot be trusted, and you have any competitors at all, they will exploit such a flaw mercilessly.

Write your documentation; you can describe the flaw without calling it a flaw or mistake, it is just the way the product is done. Arrange it so management can excise it quickly if they don't want to let people know; that is their job, and not every design flaw is exploitable, as you note some are just stupidly and unnecessarily clumsy. (A good example of that is a phone system that requires the caller to identify themselves more than once, or enter an account number more than once.)

Write it up; as an addendum or final word on a feature, or whatever. Keep your copy of the documentation with that write up. Show it to your supervisor for a final decision, along with some form of the reasoning above. They can kick it upstairs or tell you to kill it, that is a business decision they have been tasked with making. Do not presume it is your role to make it for them; it lets them (rightfully) blame you for any fallout.

Improve this answer
12
  • 2
    Oh, the joys of documenting products with bad design. Clearly point out limitations so users are at least informed. Try to provide workarounds. Mention how to obtain updates when they are available.
    – user8356
    Commented Feb 14, 2018 at 15:30
  • 2
    Just remember that these are not your decisions to make. They are the product manager's decision to make. Doing it your way and daring the product manager to force you to change it is not the way you build trust or rapport, and it could lead to a missed deadline which could cost the company money and you your job. Present the options first before you waste time on a strategy that management does not support. That will provide sufficient evidence that you raised the concern. And if you can't live with the decision management makes, quit.
    – user16226
    Commented Feb 14, 2018 at 15:58
  • 2
    @MarkBaker I've been a division manager of a product generating 80% of all revenue in a public company. It is the job of the writer to write what he knows; I would not consider that time frivolously spent; I'd consider it a more clear argument than any verbal exchange of concerns. It would be up to me, the lawyers and the board to determine the impact of omitting this information, or missing the deadline to fix it. A meeting is NOT proof without documentation, and if the boss tells you to drop it, THEN writing is disobeying orders. I still say, write it up, even if it is just a dated memo.
    – Amadeus
    Commented Feb 14, 2018 at 16:09
  • 1
    @Amadeus, yes, certainly, present the alternative in writing for all the reasons you suggest. But don't pick a strategy, execute it, and then present it as a fait accomplis. You say "Absolutely document them" that implies write the user documents that way, not write an internal memo. That is the point that needs to be made clear. Don't write anything in the docs till the business decision has been made. Do write down everything you present to management in the course of asking for a resolution of the business issue.
    – user16226
    Commented Feb 14, 2018 at 16:16
  • 1
    @Amadeus Writers cost money and most tech writing departments are chronically underfunded and understaffed. If management wants to spend the time and money to generate more than one approach to documenting the product, then they should say so. As a docs manager, I would not direct my staff to do this unless asked to do so by the PM. PMs job is to decide what they want and fund people to produce it.
    – user16226
    Commented Feb 14, 2018 at 16:29
2

Based on my experience with salesforce.com, you could always mark the feature as a Beta. You might even borrow their verbiage:

This release contains a beta version of the [xyz feature] that is production quality but has known limitations. We welcome your feedback [on some support channel].

This lets people know that the feature exists but is flawed. This helps clearly identify that there are issues you know about, but didn't have time to fix (yet).

You don't even need to explicitly state what those limitations are, until/unless specific customers that run into the flaws open support cases.

Improve this answer
1
  • This is a good idea, but the decision to use it has to come from the developers/management. A writer cannot presume to classify the status of a feature.
    – Joe
    Commented Feb 21, 2018 at 2:56

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.