GoogleCloudPlatform / GoogleCloudPlatform/spring-cloud-gcp

Improve the visibility of the official documentation link

Open
#1,244 3 comments 0 reactions 0 assignees View on GitHub
documentation priority: p3 type: enhancement
Dominant language
Java
Stars
551
Forks
349
Avg merge
1d 13h
Merged PRs (30d)
14

Description

**Describe the bug**

I had trouble locating the link to the official documentation in the readme.
I'm unsure on how to address the issue since it is related to personal perception.
It is 100% okay, if you disregard this issue. I just wanted to bring this to your attention.

**Sample**

The projects README starts with a link to spring's project page, which basically tells me, that it is no longer the official page.
I then scanned the rest of the readme.
I noticed, that there is a link to the javadocs and a few others, but I had to scroll to the end of the page to locate a link that would take me to the `documentation`.

I then proceeded to edit the readme to amend the first line to something like this:

````txt
You can check our project website [here](...) or read our documentation [here](...).
````

Before submitting a PR I checked the docs again for the link and only then I noticed that the links I wanted were actually there, and my brain just filtered them from my perception.

**Ideas**

a) Make the `documentation` in the second paragraph a link or highlight it some more.
b) or change the structure so that it doesn't look like it is all about javadocs. e.g.:

> For a deeper dive into the project, refer to our documentation:
>
> * [Spring Cloud GCP Latest](https://googlecloudplatform.github.io/spring-cloud-gcp/reference/html/index.html)
> * [Spring Cloud GCP 3.3.0](https://googlecloudplatform.github.io/spring-cloud-gcp/3.3.0/reference/html/index.html)
> * [Spring Cloud GCP 2.0.10](https://googlecloudplatform.github.io/spring-cloud-gcp/2.0.10/reference/html/index.html)
> * [Javadocs Latest](https://googleapis.dev/java/spring-cloud-gcp/latest/index.html)

Please note that IMO the `Spring Cloud GCP Reference` part just adds noise to that sentence.

Contributor guide

Open the contributing guide

Research direction

Start in the repository README, especially its opening paragraphs and the existing Spring Cloud GCP documentation and Javadocs links. Compare the current presentation with the issue's suggested structures; done means the official documentation link is easy to find without scanning to the end.

Written by the indexing model from the issue text.

Assessment

Tech stack
google-cloud, java, spring
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.