Skip to main content

Best practices

As a company, updating documentation for our users and development team is vital. We intend to capture and share knowledge, experiences, and processes so everyone can understand them effectively.

This guide will provide you with best practices for editing a file from our documentation.

Markdown format​

Our documentation uses the Markdown language, which combines the simplicity of plain text formatting with the ability to add formatting and structure. It comprises different rules, which you can learn more about here.

Add images​

It is important to remember that the images used in our documentation are hosted on the Cloudinary platform. To add an image, follow these steps:

  1. Login to Cloudinary through Okta. If you don't have this application in your panel, you can find instructions on how to add it here.

  2. After logging in to Cloudinary, navigate to the folder where you want to save the new image.

  3. Upload the image to that folder and give it a descriptive name.

  4. Copy the link to the uploaded image by clicking on the first option in the top right corner.

  5. Remember to follow the formatting guidelines for mounting images, which are as follows:

  ![image name](URL of the Image in Cloudinary)

Common changes editing an md file​

  • Updating Images: It is important to remember that the images used in our documentation are hosted on the Cloudinary platform. If you need to update an image, follow these steps:

    1. Navigate to the folder where the original image is stored in Cloudinary.

    2. Rename the new image with the same name as the previous one.

    3. Replace the old image with the new one in the folder.

    4. Confirm the action when asked.

To ensure that the image update was successful, go to the section of the documentation where you want to apply the change and refresh the page, which will reflect the successful change.

  • Optimizing the Slug: A slug uniquely identifies web pages and resources. For this reason, clarity and description in slugs is critical. Below, we provide simple steps to update a slug in the documentation:

    1. New Slug Definition: Choose a new slug that is brief but highly descriptive. As an example, let's consider the following URL: https://docs.fluidattacks.com/tech/ci/installation. As you can see, it is related to the agent installation. Instead of using the full term "agent," you can abbreviate it to "ci," creating a short but more intuitive slug for the user. Once you have this new name, modify the corresponding .md file.

    2. Update in the .md file: Modify the corresponding .md file with the new slug in the relevant places, including the file name and the identifier (id).

    3. Adjustments in sidebar.js: Adjust the new slug in the sidebar.js file.

  • Broken links due to slug changes: When you modify a slug and other pages depend on it for redirection, errors will occur in the links of those files. To prevent this situation, remember that when you update a slug, you must also make the necessary changes to the files that carry out these redirects.

    Ensure ti review all affected files and update any links or references to the old slug to reflect the new slug. This includes updating links within markdown files, as well as any references in other parts of the documentation such as navigation menus or sidebar links.

    By keeping all references consistent with the updated slug, you can ensure that users can navigate the documentation smoothly without encountering broken links or redirects to incorrect pages.

Grammar​

Accuracy and clarity in documentation are essential to convey information effectively. Our documentation is based in English, and there must be no grammatical errors to convey the message clearly and confidently.

Here is a list of tools to help you write better:

Last updated on