Move examples and docs out of the README, point to docs instead #672
Assignees
Comments
|
I think the readme's job is to quickly make the sell on why gcloud is awesome, and part of that is shoving in the potential user's face how easy it is to "..." as soon as you can. A user going to a readme to look for the link to further documentation is common practice, so I would rather solve how to get the user to see our API documentation links than have the readme completely cater to the user rather than the maybe-user. Since we already link to the docs at the top of the page and in each service's sub-section, is it possible to get opinions from the users who sourced this feedback to see what we could do better? |
|
I'll have our UX guy share the results at the end, but it was super clear that the person just wasn't getting to the docs because they thought the README was all there was. Can we add "for more details on , check out the docs here: " right after the example sections? Our goal is to funnel people to the gh-pages site ASAP. |
|
Were the participants of the study Node developers? We're super tuned in to the patterns of GitHub + npm + API docs, and how and when to use each resource.
👍 |
|
They were, but this one in particular was not SUPER experienced, I'd say a 5/10 Node dev. |
4 tasks
sofisl
pushed a commit
that referenced
this issue
Oct 11, 2022
[](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [@google-cloud/automl](https://togithub.com/googleapis/nodejs-automl) | [`^2.0.0` -> `^3.0.0`](https://renovatebot.com/diffs/npm/@google-cloud%2fautoml/2.5.2/3.0.0) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>googleapis/nodejs-automl</summary> ### [`v3.0.0`](https://togithub.com/googleapis/nodejs-automl/blob/HEAD/CHANGELOG.md#​300-httpsgithubcomgoogleapisnodejs-automlcomparev252v300-2022-06-20) [Compare Source](https://togithub.com/googleapis/nodejs-automl/compare/v2.5.2...v3.0.0) ##### ⚠ BREAKING CHANGES - update library to use Node 12 ([#​613](https://togithub.com/googleapis/nodejs-automl/issues/613)) ##### Bug Fixes - Add back java_multiple_files option to the text_sentiment.proto to match with the previous published version of text_sentiment proto ([20995db](https://togithub.com/googleapis/nodejs-automl/commit/20995db72854243213a6ffabcb188a52c9cef8f6)) - proto field markdown comment for the display_name field in annotation_payload.proto to point the correct public v1/ version ([20995db](https://togithub.com/googleapis/nodejs-automl/commit/20995db72854243213a6ffabcb188a52c9cef8f6)) ##### Build System - update library to use Node 12 ([#​613](https://togithub.com/googleapis/nodejs-automl/issues/613)) ([9ddf084](https://togithub.com/googleapis/nodejs-automl/commit/9ddf0845c8f5f1a2434a1f48d3740447fa2d747d)) ##### [2.5.2](https://www.github.com/googleapis/nodejs-automl/compare/v2.5.1...v2.5.2) (2021-12-30) ##### Bug Fixes - **deps:** update dependency csv to v6 ([#​565](https://www.togithub.com/googleapis/nodejs-automl/issues/565)) ([7f1d947](https://www.github.com/googleapis/nodejs-automl/commit/7f1d9477cfa2d9697206dffabdfb92dfb80bc1d1)) ##### [2.5.1](https://www.github.com/googleapis/nodejs-automl/compare/v2.5.0...v2.5.1) (2021-11-08) ##### Bug Fixes - **deps:** update dependency mathjs to v10 ([#​559](https://www.togithub.com/googleapis/nodejs-automl/issues/559)) ([120a457](https://www.github.com/googleapis/nodejs-automl/commit/120a457211590c48c0e8d81e35e364f6c098dbce)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - "after 9am and before 3pm" (UTC), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, click this checkbox. --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/nodejs-language).
Closed
sofisl
pushed a commit
that referenced
this issue
Oct 13, 2022
[](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [@google-cloud/automl](https://togithub.com/googleapis/nodejs-automl) | [`^2.0.0` -> `^3.0.0`](https://renovatebot.com/diffs/npm/@google-cloud%2fautoml/2.5.2/3.0.0) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>googleapis/nodejs-automl</summary> ### [`v3.0.0`](https://togithub.com/googleapis/nodejs-automl/blob/HEAD/CHANGELOG.md#​300-httpsgithubcomgoogleapisnodejs-automlcomparev252v300-2022-06-20) [Compare Source](https://togithub.com/googleapis/nodejs-automl/compare/v2.5.2...v3.0.0) ##### ⚠ BREAKING CHANGES - update library to use Node 12 ([#​613](https://togithub.com/googleapis/nodejs-automl/issues/613)) ##### Bug Fixes - Add back java_multiple_files option to the text_sentiment.proto to match with the previous published version of text_sentiment proto ([20995db](https://togithub.com/googleapis/nodejs-automl/commit/20995db72854243213a6ffabcb188a52c9cef8f6)) - proto field markdown comment for the display_name field in annotation_payload.proto to point the correct public v1/ version ([20995db](https://togithub.com/googleapis/nodejs-automl/commit/20995db72854243213a6ffabcb188a52c9cef8f6)) ##### Build System - update library to use Node 12 ([#​613](https://togithub.com/googleapis/nodejs-automl/issues/613)) ([9ddf084](https://togithub.com/googleapis/nodejs-automl/commit/9ddf0845c8f5f1a2434a1f48d3740447fa2d747d)) ##### [2.5.2](https://www.github.com/googleapis/nodejs-automl/compare/v2.5.1...v2.5.2) (2021-12-30) ##### Bug Fixes - **deps:** update dependency csv to v6 ([#​565](https://www.togithub.com/googleapis/nodejs-automl/issues/565)) ([7f1d947](https://www.github.com/googleapis/nodejs-automl/commit/7f1d9477cfa2d9697206dffabdfb92dfb80bc1d1)) ##### [2.5.1](https://www.github.com/googleapis/nodejs-automl/compare/v2.5.0...v2.5.1) (2021-11-08) ##### Bug Fixes - **deps:** update dependency mathjs to v10 ([#​559](https://www.togithub.com/googleapis/nodejs-automl/issues/559)) ([120a457](https://www.github.com/googleapis/nodejs-automl/commit/120a457211590c48c0e8d81e35e364f6c098dbce)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - "after 9am and before 3pm" (UTC), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, click this checkbox. --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/nodejs-language).
4 tasks
sofisl
pushed a commit
that referenced
this issue
Nov 10, 2022
[PR](googleapis/gapic-generator-typescript#878) within updated gapic-generator-typescript version 1.4.0 Committer: @summer-ji-eng PiperOrigin-RevId: 375759421 Source-Link: googleapis/googleapis@95fa72f Source-Link: googleapis/googleapis-gen@f40a343
sofisl
pushed a commit
that referenced
this issue
Nov 11, 2022
[](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [jsdoc](https://togithub.com/jsdoc/jsdoc) | [`^3.6.3` -> `^4.0.0`](https://renovatebot.com/diffs/npm/jsdoc/3.6.11/4.0.0) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>jsdoc/jsdoc</summary> ### [`v4.0.0`](https://togithub.com/jsdoc/jsdoc/blob/HEAD/CHANGES.md#​400-November-2022) [Compare Source](https://togithub.com/jsdoc/jsdoc/compare/3.6.11...084218523a7d69fec14a852ce680f374f526af28) - JSDoc releases now use [semantic versioning](https://semver.org/). If JSDoc makes backwards-incompatible changes in the future, the major version will be incremented. - JSDoc no longer uses the [`taffydb`](https://taffydb.com/) package. If your JSDoc template or plugin uses the `taffydb` package, see the [instructions for replacing `taffydb` with `@jsdoc/salty`](https://togithub.com/jsdoc/jsdoc/tree/main/packages/jsdoc-salty#use-salty-in-a-jsdoc-template). - JSDoc now supports Node.js 12.0.0 and later. </details> --- ### Configuration 📅 **Schedule**: Branch creation - "after 9am and before 3pm" (UTC), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/nodejs-asset). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNC4xNy4xIiwidXBkYXRlZEluVmVyIjoiMzQuMTcuMSJ9-->
4 tasks
4 tasks
sofisl
pushed a commit
that referenced
this issue
Jan 10, 2023
](https://renovatebot.com){kind=link}
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
We're seeing people using the README contents on NPM as a source of real documentation, and missing out on the bigger picture because they're not seeing all of the other pieces.
Any objections to removing the README example content (specific snippets for each service) and pointing to the gh-pages docs instead?
The text was updated successfully, but these errors were encountered: