First thing that comes to my mind:
We don't have a proper template for issues (like the one for NVDA).
It is hard to comment without having a proper description of the issue (#6) and its pull request (#7).
I don't like reading the diff to gather the info.

In principle, I'm in favour of splitting.

I don't like that we use the readme.md for the help.
It should be reserved for GitHub and include the following:

• AddOn summary/description/introduction
• links to releases/community addons
• link to the addon help (should be covered with the preceding point).
• a link to the templates readme, i.e. how to built the addon (one can link to markdown documents in GitHub)
• how to contribute/give feedback (e.g. for the bitbucket version of the readme or from the addon manager)
• change log

In other words, the help would be modular.

The user has different needs at different stages of his involvement with the addon:

1. First time discovery. This should include a gentle introduction and make the user want more. Could include audio/video presentations.
   The official community homepage lists just addons without indicating their functionality by other means than its title. That's not likely to hook someone, is it.
   Thus, there should be a intro.md that could water the user's mouth without compelling them to navigate to the full page.
   And do not let us forget the system requirements.
2. After installation. The help file shouldn't be written in the same style as above, the summary would suffice, followed by the actual description of the functionality.
3. Instant help, this is mainly for appModules, it should only list, application specific, additional gestures.
   Why not extending the NVDA+Control+F1 functionality (e.g. double-press) which could pop up "usage.md" for the active application, optionally listing global (module) hotkeys that are relevant for this document.
   (As a side note, I would wish that authors would gather app gestures in a separate application category of the input gestures dialog and not under existing categories, this would make modifying them easier.)
   Could also be a manually crafted or generated "gestures.md" module.
4. Updating the addon. Currently, the user is prompted to update the addon without given any information about changes.
   Publishing them through posts in the NVDAAddon mailing list is a poor replacement IMHO.
   So why not pulling the information from changelog.md? For instance, the manifest could have an (optional) entry for that. If the updater finds that entry, it could list all the changes from the currently installed addon up to the new one in a description field. A lazier solution would be to list commit messages for the given period.
5. Contributions. How the addon should be forked, build and what dependencies are needed, essentially the current readme of the template.

I'm talking here about markdown files but in some cases, they would actually be translated html files.

Hi,

Coming back after more than a year...

I think GitHub wiki might be a better place to host user level documentation (at least based on my setup at the moment).

Thanks.