= Contributing to documentation == Rendering documentation locally Install docs build requirements: [,bash] ---- make docs-dependencies ---- To render the user-facing documentation site locally: [,bash] ---- make docs-user ---- To render the contributor documentation site locally: [,bash] ---- make docs-dev ---- The built HTML files are in `docs_build/adoption-user` and `docs_build/adoption-dev` directories respectively. There are some additional make targets for convenience. The following targets, in addition to rendering the docs, will also open the resulting HTML in your browser so that you don't have to look for it: [,bash] ---- make docs-user-open # or make docs-dev-open ---- The following targets set up an inotify watch on the documentation sources, and when it detects modification, the HTML is re-rendered. This is so that you can use "edit source - save source - refresh browser page" loop when working on the docs, without having to run `make docs-*` repeatedly. [,bash] ---- make docs-user-watch # or make docs-dev-watch ---- === Preview of downstream documentation To render a preview of what should serve as the base for downstream docs (e.g. with downstream container image URLs), prepend `BUILD=downstream` to your make targets. For example: [,bash] ---- BUILD=downstream make docs-user ---- == Patterns and tips for contributing to documentation * Pages concerning individual components/services should make sense in the context of the broader adoption procedure. While adopting a service in isolation is an option for developers, let's write the documentation with the assumption the adoption procedure is being done in full, going step by step (one doc after another). * The procedure should be written with production use in mind. This repository could be used as a starting point for product technical documentation. We should not tie the documentation to something that wouldn't translate well from dev envs to production. ** This includes not assuming that the source environment is Standalone, and the destination is CRC. We can provide examples for Standalone/CRC, but it should be possible to use the procedure with fuller environments in a way that is obvious from the docs. * If possible, try to make code snippets copy-pastable. Use shell variables if the snippets should be parametrized. Use `oc` rather than `kubectl` in snippets. * Focus on the "happy path" in the docs as much as possible, troubleshooting info can go into the Troubleshooting page, or alternatively a troubleshooting section at the end of the document, visibly separated from the main procedure. * The full procedure will inevitably happen to be quite long, so let's try to be concise in writing to keep the docs consumable (but not to a point of making things difficult to understand or omitting important things). * A bash alias can be created for long command however when implementing them in the test roles you should transform them to avoid command not found errors. From: + [,bash] ---- alias openstack="oc exec -t openstackclient -- openstack" openstack endpoint list | grep network ---- + To: + [,bash] ---- alias openstack="oc exec -t openstackclient -- openstack" ${BASH_ALIASES[openstack]} endpoint list | grep network ----