Define Security Products Documentation Strategy

Problem to solve

There are already a number of issues that discuss improving the documentation around our ~Secure products. We have open discussions around the quality, information architecture, location, and strategies but many of these feel symptomatic rather than unifying with an overall strategy.

This issue is to discuss our preferred documentation strategy that will drive how we respond to issues around documenting our tools.

Further details

What do we want to document and What do we want to avoid documenting?

All documentation is a tradeoff between cost of maintenance of the documentation and providing maximum flexibility to our users, however with work on exposing more configuration (i.e. https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9676 and gitlab-org/security-products/sast!122 (merged)) we are moving further away from convention-over-configuration.

Related issues around documentation:

Proposal

Reach internal consensus on a strategy for documenting Security Products including where product documentation should live (READMEs or gitlab-docs) and what should be documented.

Who can address the issue

cc @gl-secure