Separate repository documentation from add-on help file

[tseykovets]

Problem description

Currently, the add-on’s help documentation is generated from the README.md file located in the root of the repository. This creates a conflict of purposes:

• The README.md is a standard file for describing the repository itself — it should contain technical details, development instructions, build guides, contribution guidelines, etc.
• At the same time, it is used as the source for the end-user help file distributed with the add-on.

This limitation forces developers to either:

• compromise on the content of the README.md, omitting important technical details to keep it user-friendly for end users;
• include technical content that might be confusing or irrelevant for end users who view the help file inside NVDA;
• maintain two separate files and manually sync content, which is error-prone and inefficient.

Proposed solution

To resolve this conflict, I propose modifying the template structure as follows:

1. Introduce a dedicated help.md file for the add-on’s user documentation instead of readme.md.
2. Allow README.md to be used solely for repository documentation. The root README.md should focus on development, building, contributing, and other technical aspects relevant to developers and contributors.
3. Update the build process to generate help.html from help.md (instead of from README.md).
4. Modify the add-on manifest by updating the docFileName parameter in the generated manifest.ini to point to help.html.

Benefits

• Clear separation of concerns: README.md for developers, help.md for end users.
• Improved developer experience: Developers can freely enhance the README.md with build instructions, pre-commit setup, VS Code configs, etc., without affecting the end-user help.
• Better user experience: The end-user help (help.html) can be tailored specifically for NVDA users, focusing on how to use the add-on, without technical clutter.
• Maintainability: Easier to maintain and update both sets of documentation independently.
• Consistency: Aligns with the logical naming convention.

Impact

• Backwards compatibility: This change will affect existing add-ons using the template. A migration guide should be provided.
• Documentation update: The README and usage sections of the template must be updated to reflect the new file structure and build process.

Acceptance criteria

After implementing this change:

• A new add-on created from the template has a help.md file for user documentation.
• The build process generates a help.html file from help.md.
• The generated manifest.ini contains docFileName=help.html.
• The root README.md is not used for generating the help file and can contain any developer-oriented content.