Best Practices for Documentation

Oct 13, 2025 by talynt.org 75 views

Docs Bug 🐞 report: keyword "newLines" should be changed to "indent" at one place on "Creating a Template page"

Describe the bug you found in AsyncAPI Docs.

While reading the "Creating a template" docs, I found that there is a bug in the documentation. Under section 5c, it is mentioned that the template code to generate these functions will look like this:

However, adding this code to the template file is causing an error of object not found due to incorrect indentation in the generated code. This issue arises from the fact that the keyword "newLines" is used instead of "indent" in the code snippet.

The Corrected Code

To resolve this issue, the code should be changed to:

<Text indent={2}>
        <TopicFunction channels={asyncapi.channels().filterByReceive()} />
</Text>

Alternatively, it may also be changed to:

<Text newLines={2} indent={2}>
        <TopicFunction channels={asyncapi.channels().filterByReceive()} />
</Text>

Both of these code snippets will work fine and generate the correct code with proper indentation.

Impact of the Bug

The bug in the documentation has a significant impact on users who are trying to create a template page using the provided code snippet. The incorrect indentation in the generated code can lead to errors and make it difficult for users to understand the correct syntax and usage of the code.

Solution to the Bug

To fix this bug, the documentation team should update the code snippet in section 5c to use the correct keyword "indent" instead of "newLines". This will ensure that users can create a template page without any errors and can easily understand the correct syntax and usage of the code.

Best Practices for Documentation

To avoid similar bugs in the future, it is essential to follow best practices for documentation. This includes:

Thorough testing: Test the code snippets and examples provided in the documentation to ensure that they work correctly and do not cause any errors.
Code review: Review the code snippets and examples provided in the documentation to ensure that they are accurate and up-to-date.
User feedback: Encourage users to provide feedback on the documentation and fix any bugs or issues that are reported.

Conclusion

In conclusion, the bug in the "Creating a template" docs is a significant issue that needs to be addressed. By updating the code snippet to use the correct keyword "indent" instead of "newLines", users can create a template page without any errors and can easily understand the correct syntax and usage of the code. This will improve the overall user experience and make the documentation more accurate and reliable.

Attach any resources that can help us understand the issue.

Code of Conduct

[x] I agree to follow this project's Code of Conduct
Docs Bug 🐞 report: keyword "newLines" should be changed to "indent" at one place on "Creating a Template page"

Q&A: Frequently Asked Questions about the Bug

Q: What is the bug in the "Creating a template" docs?

A: The bug in the "Creating a template" docs is that the keyword "newLines" is used instead of "indent" in the code snippet, which causes incorrect indentation in the generated code.

Q: What is the impact of the bug?

A: The bug has a significant impact on users who are trying to create a template page using the provided code snippet. The incorrect indentation in the generated code can lead to errors and make it difficult for users to understand the correct syntax and usage of the code.

Q: How can I fix the bug?

A: To fix the bug, you can update the code snippet in section 5c to use the correct keyword "indent" instead of "newLines". This will ensure that users can create a template page without any errors and can easily understand the correct syntax and usage of the code.

Q: What are the best practices for documentation to avoid similar bugs in the future?

A: To avoid similar bugs in the future, it is essential to follow best practices for documentation, including:

Thorough testing: Test the code snippets and examples provided in the documentation to ensure that they work correctly and do not cause any errors.
Code review: Review the code snippets and examples provided in the documentation to ensure that they are accurate and up-to-date.
User feedback: Encourage users to provide feedback on the documentation and fix any bugs or issues that are reported.

Q: How can I provide feedback on the documentation?

A: You can provide feedback on the documentation by reporting any bugs or issues you encounter. You can also suggest improvements to the documentation and provide feedback on the accuracy and clarity of the content.

Q: What is the Code of Conduct for this project?

A: The Code of Conduct for this project is to follow the project's guidelines and rules for contributing to the documentation. This includes being respectful and professional in your interactions with other users and contributors, and following the project's guidelines for reporting bugs and issues.

Additional Resources

Documentation Guidelines: For more information on the documentation guidelines and best practices, please refer to the project's documentation guidelines.
Code of Conduct: For more information on the Code of Conduct, please refer to the project's Code of Conduct document.
Reporting Bugs: For more information on reporting bugs and issues, please refer to the project's bug reporting guidelines.

Conclusion

In conclusion, the bug in the "Creating a template" docs is a significant issue that needs to be addressed. By following the best practices for documentation and providing feedback on the documentation, users can help ensure that the documentation is accurate and reliable. If you have any further questions or concerns, please do not hesitate to reach out.