Chapter 6: Documenting Third-party Products¶
This chapter looks at how to handle documentation when your software relies on a third-party product (a product not created by your company). It opens by stating the general principle of not documenting third-party products, then discusses when you may need to make an exception to this rule. It provides a helpful decision flowchart.
Discussion Summary¶
Generally, community discussion supported the advice in the chapter: link to the third-party documentation (keep an eye out for links changing!), and if you must document it yourself, keep it as simple as possible. The exceptions to the rule were generally for details and workarounds specific to your own product: in that case, you do need to provide some guidance.
However, some contributors did make the case for producing your own docs for third-party products. Reasons in favour included getting your own branding on materials, and taking a particular approach or style (such as wanting task-specific documentation). It can also be frustrating for your customers if you direct them to poor third-party docs.
Writers shared experience of pushing back on requests: for example, a writer asked to “clean up” some third-party documentation successfully made the case for not reinventing the wheel (it helped that the third-party docs were good). There is also the issue of docs’ team time: if your product has lots of integrations, documenting them all isn’t viable.
There were anecdotes of working with other companies to encourage them to improve their docs. It is tricky to document a product you don’t have full access to, and where you probably don’t have access to SMEs (subject matter experts). If possible, encourage the company to document their own product.
Writers who have had to document third-party products shared tips to minimize the pain:
- Don’t commit to maintaining screenshots.
- Include disclaimers that the doc may not be up to date and point readers to the third-party docs.
- Can your devs include the documentation in testing? This reduces the chance of them becoming outdated.
- If you are dealing with lots of integrations, can your support team write guides as they deal with problems, then share them on customer forums or blog posts? This keeps it out of the official documentation.
