Precise GitHub links for editing documentation
zzap opened this issue · comments
Feature Request
- Yes, I reviewed the contribution guidelines.
Problem
When visiting a command documentation page, such as wp cli alias I would expect that contributing to this page is where the GitHub icon would take me.
However, this link just leads to wp-cli/wp-cli repo, as does the wp cli command. This makes it very difficult to find the the correct place for contributing with documentation.
Even with other commands, with separate GitHub repositories, this link goes only to the repo itself requiring from contributor to find the exact file and line in code.
This means that contributing to documentation requires deep understanding of how the project is organised and how the parser works, which is really unnecessary and can have effect in people not bothering to contribute.
Proposal
If GitHub links would lead to exact file and line (the first line of docs block) it would make contributing so much more easier and flowing experience.
The GitHub icon is indeed meant to represent the repository as a whole, with the buttons next to it providing repository-specific actions. Also, to be honest, it is even hard to recognize it does something, as it doesn't look like a link or button.
I think it would be preferable to adapt this so that it falls in line with the "Handbook" part of the documentation, so that there's an "Edit" button next to the title of the section:
What do you think about that approach?
Here's the document where I started adding links to GitHub file/line of code for each command.
https://docs.google.com/spreadsheets/d/1De8NXFRAzRofGjzHigSbdbiGpuFwZLLyNomiFhKnd3Y/edit?usp=sharing
I hope to get them all done soon.
@zzap Oh no, I think you misunderstood me.
This should automatically generated based on the source code. Otherwise we'll have hundreds of links we'll need to check after each code change. Please don't waste more time on this, I'll write a parser to extract this data out of the source files.
We already try to simplify this by providing an overview in the issue templates: https://github.com/wp-cli/.github/blob/master/.github/ISSUE_TEMPLATE/1-BUG_REPORT.md#L20-L44
But yes, additional documentation in the handbook itself would be better.