Precise GitHub links for editing documentation

[zzap]

Feature Request

• [x] 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.

[schlessera]

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?

[zzap]

Yes, that's even better and more obvious. I like it.

On Fri, 20 Sep 2019, 17:37 Alain Schlesser, [email protected] wrote:

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: [image: Image 2019-09-20 at 5 34 51 PM] https://user-images.githubusercontent.com/83631/65339855-3a09a500-dbcd-11e9-8d2a-804bd505df1e.png What do you think about that approach?

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/wp-cli/handbook/issues/340?email_source=notifications&email_token=AALQMYYNM4CPUV4QSLZEDQLQKTU3XA5CNFSM4IYWKLZ2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7HCVEA#issuecomment-533605008, or mute the thread https://github.com/notifications/unsubscribe-auth/AALQMY25Q37GWGXBQVDYLNDQKTU3XANCNFSM4IYWKLZQ .

[zzap]

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.

[schlessera]

@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.

[zzap]

I started writing this doc before we chat about this because I couldn't wrap my head around the structure :) I understood it will be parsed.

I'm thinking more about documentation about how to contribute to documentation (links to actual files and lines are just in case I need it until the parser is ready). In this document the most important info is the actual GitHub repo because I think it would be useful to have list of commands and their actual repos in contributing Handbook page https://make.wordpress.org/cli/handbook/contributing/#improving-our-documentation, next to explanation that each command has/will have a link to exact file/code line. I think this would be helpful to people who start getting involved from Handbook, rather than commands docs as I did. I intend to try to improve that part of WP CLI Handbook as I found it somewhat incomplete.

[schlessera]

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.