wp-cli / handbook

📖 Complete documentation for WP-CLI
https://make.wordpress.org/cli/handbook/
MIT License
188 stars 329 forks source link

Precise GitHub links for editing documentation #340

Open zzap opened 4 years ago

zzap commented 4 years ago

Feature Request

- [x] Yes, I reviewed the [contribution guidelines](https://make.wordpress.org/cli/handbook/contributing/). **Problem** When visiting a command documentation page, such as [wp cli alias](https://developer.wordpress.org/cli/commands/cli/alias/) I would expect that contributing to this page is where the GitHub icon would take me. ![GitHub link to command](https://s.nimbusweb.me/attachment/3337515/vhurm0x9xu9ybxh0hpbh/0vBNU4Mlsu2TFzkB/screenshot-developer.wordpress.org-2019.09.20-13-56-01.png) However, this link just leads to [wp-cli/wp-cli](https://github.com/wp-cli/wp-cli) repo, as does the [wp cli](https://developer.wordpress.org/cli/commands/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 commented 4 years ago

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 2019-09-20 at 5 34 51 PM What do you think about that approach?

zzap commented 4 years ago

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

On Fri, 20 Sep 2019, 17:37 Alain Schlesser, notifications@github.com 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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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.