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.
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.
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:
After logging in to Cloudinary, navigate to the folder where you want to save the new image.
Upload the image to that folder and give it a descriptive name.
Copy the link to the uploaded image by clicking on the first option in the top right corner.
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:
Navigate to the folder where the original image is stored in Cloudinary.
Rename the new image with the same name as the previous one.
Replace the old image with the new one in the folder.
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:
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.
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).
Adjustments in sidebar.js: Go to the
sidebar.jsfile 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.
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.