Cloud Databases documentation

This repo contains documentation common to the IBM Cloud Databases services, encompassing:

• Databases for Elasticsearch
• Databases for etcd
• Databases for MongoDB
• Databases for PostgreSQL
• Databases for Redis
• Messages for RabbitMQ
• Databases for MySQL

These docs do not have an attached catalog entry, and do not show up as a distinct service on the docs pages. They are linked to in the Table of Contents in the above services' documentation.

Contacts for this repo

• Andrea Lang: ANDREAL, andreal@de.ibm.com
• Slack channel: #icd-docs

Creating content

Follow these steps to add to the deployment guide docs.

ℹ️ Tip: If you'd rather give feedback about the documentation, create an issue.

Before you begin

Set up your local development environment.

• Visual Studio Code is the recommended editor. For more information, see Choose an editor.
• You can install a Markdown linter in Visual Studio Code that works with IBM Cloud docs. For more information, see Integrating the Markdown linter in VS Code.

Drafting content

All content starts from the source branch.

1. Clone this repo if you have write privileges. Otherwise, fork the repo.

2. Create a working branch from the source branch.

3. Make your changes to the Markdown content.

   • Cloud docs uses Markdown with a few custom extensions to source the docs. For tips about how to structure and style your docs with IBM Cloud Markdown, see Quick tips for authoring in IBM Cloud docs in "Creating solution, deployment, and migration guides".
   • Cloud docs also supports controlling content with tagging. For example, content within the staging code tags is not displayed to the public. For more information, see Making updates to your docs.

4. Commit your updates.

5. Create a pull request from your branch or fork to source.

   1. A Jenkins job runs that commits content to the draft and review branches and opens a pull request to the publish branch.
   2. After a few minutes, you can see your changes in the IBM Cloud docs framework. Changes to draft are available at the internal /docs-draft/ location (https://test.cloud.ibm.com/docs-draft/cloud-databases). Changes to review are available at the pre-production /docs/ location (https://test.cloud.ibm.com/docs/cloud-databases).

ℹ️ Tip: Content that is tagged with draft, review, or staging, or feature tags are built and promoted only to the internal location and is not included in the pull request to the publish branch for production.

Publishing to production

When content is committed to the source branch, a pull request is created from a branch called next-prod-push to the publish branch. So, changes can't go into the branch until they are reviewed, edited, and approved by a one of the doc maintainers.

The documentation team reviews your PR and might request changes.

• If the changes are relatively straightforward and self-contained, such as a corrected typographical error or a rewritten sentence, we will approve and merge them after issues are addressed.
• If the changes are more extensive, such as a significant rewrite or entirely new content, the documentation team might need to make revisions for editorial or style reasons.⁠ In this case, we might open a new PR against your branch with our proposed revisions.⁠ You can then review these revisions and incorporate the changes into your branch.⁠ After the documentation team is satisfied with the proposed changes, we merge your PR.⁠ When changes are merged to the production branch, they are built and published to production at https://cloud.ibm.com/docs/cloud-databases.

Guidelines for merging a PR

As someone with merge responsibilities, follow these guidelines and practices to make sure that changes are released consistently.

• Make sure that the merge commit message is clear and specific.

  ❗ Important: Do not expose IBM Confidential information in your commit message to publish. Commits made to the publish branch become public record. When you merge to the publish branch, the source is mirrored in a public GitHub repo at https://github.com/ibm-cloud-docs/cloud-databases so that customers can view and contribute to the source.

• Squash and merge

  • Use the Squash and merge option when you merge a PR. Status checks prevent the merge if the squash and merge method is not used. For more information, see Squashing your merge commits.

Monitoring

After a build is triggered by a commit or merge, you can monitor progress.

Monitoring builds

The Slack channel #docs-cloud-databases displays information about builds.

Monitoring content quality

You can monitor your content quality on the Content Quality Dashboard (CQD): https://cops.console.test.cloud.ibm.com/docs-quality-dashboard. The CQD for docs content is updated daily For more information, see https://test.cloud.ibm.com/docs-internal/writing?topic=writing-cqd.

More information

• Learn about the suggested content for each type of solution docs at https://test.cloud.ibm.com/docs-internal/writing?topic=writing-writing-solution.

Output

The output from the draft branch is available on the staging server:

• Staging Docs

The output from the publish branch is mirrored on github.com and available in production:

• Production Docs

Resources

• Getting started: writing docs for IBM Cloud
• IBM Cloud doc build

For general questions about IBM Cloud Databases, see the icd-questions channel

Blog Submissions

To submit a blog, go here. Ian Smalley handles everything blog-related, so any updates go through him. Use the same form to update, just make a note that it's an update, not a new post.