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 in the following link.

Add images​

It is important to remember that the images used in our documentation are hosted on the Cloudinary platform. To add an image, you have to 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 using the following link.

  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. At this point, you will be asked to confirm if you want to update the image. Confirm the action.

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: It is recommended to 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: In the above file, replace the old slug with the new one in the relevant places, including the file name and the identifier (id).

    3. Adjustments in sidebar.js: Go to the sidebar.js file and locate the old slug. Make the change to the new slug you have defined.

  • 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.

    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 get the message clearly and confidently.

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

Last updated on