fix docs banner text #207

urfreespace · 2022-09-08T07:48:27Z

Unreleased version banner

Maintained version banner

Unmaintained version banner

Signed-off-by: Li Li <urfree@apache.org>

momo-jun · 2022-09-08T08:16:42Z

site2/website-next/src/theme/DocVersionBanner/index.js

@@ -25,7 +25,7 @@ function UnreleasedVersionLabel({ siteTitle, versionMetadata }) {
      }}
    >
      {
-        "This is unreleased documentation for {siteTitle} {versionLabel} version."
+        "This documentation is for an unreleased {siteTitle} {versionLabel} version of Apache Pulsar. "


Seems {siteTitle} is duplicate with Apache Pulsar, and maybe {versionLabel} can also be removed.

Suggested change

"This documentation is for an unreleased {siteTitle} {versionLabel} version of Apache Pulsar. "

"This documentation is for an unreleased version of Apache Pulsar. "

Agree. Simply writing "an unreleased version" works fine for me.

tisonkun · 2022-09-08T09:24:37Z

site2/website-next/src/theme/DocVersionBanner/index.js

@@ -25,7 +25,7 @@ function UnreleasedVersionLabel({ siteTitle, versionMetadata }) {
      }}
    >
      {
-        "This is unreleased documentation for {siteTitle} {versionLabel} version."
+        "This documentation is for an unreleased {siteTitle} {versionLabel} version of Apache Pulsar. "


Suggested change

"This documentation is for an unreleased {siteTitle} {versionLabel} version of Apache Pulsar. "

"This documentation is for an unreleased version of Apache Pulsar. "

Agree. Simply writing "an unreleased version" works fine for me.

tisonkun · 2022-09-08T09:25:06Z

site2/website-next/src/theme/DocVersionBanner/index.js

@@ -41,7 +41,7 @@ function UnmaintainedVersionLabel({ siteTitle, versionMetadata }) {
      }}
    >
      {
-        "This is documentation for {siteTitle} {versionLabel}, which is no longer actively maintained."
+        "This documentation is for an out-of-date {siteTitle} {versionLabel} version of Apache Pulsar. "


Suggested change

"This documentation is for an out-of-date {siteTitle} {versionLabel} version of Apache Pulsar. "

"This documentation is for an out-of-date version of Apache Pulsar. "

Ditto. The sidebar and URL should already identify which version it is.

Anonymitaet · 2022-09-08T10:30:39Z

Thanks! @urfreespace

☘️☘️☘️ Banner wording

Can we consider using the following?

🔹🔹 🔹

For Next docs:

This is unreleased documentation for Next.
For the latest stable version, see 2.10.x.

🔹🔹 🔹

For the latest stable doc version (eg. 2.10.x):

This is the latest stable version 2.10.x.

🔹🔹 🔹

For docs in the maintenance cycle (eg. 2.9.x, 2.8.x):

This is the documentation for 2.9.x
For the latest stable version, see 2.10.x.

🔹🔹 🔹

For docs not in the maintenance cycle (eg. versions prior to 2.8.x):

This is the documentation for 2.6.2, which is no longer actively maintained.
For the latest stable version, see 2.10.x.

☘️☘️☘️ Banner color

Blue is more appropriate than yellow/red here.

Yellow / red can be used to indicate important hints, tips, guidance, restrictions, advice that might be overlooked, or the possibility of damage to software.

If yellow / red is overused, they lose their significance.

Thoughts? @tisonkun @momo-jun @DaveDuggins @D-2-Ed

Anonymitaet · 2022-09-08T10:49:59Z

site2/website-next/scripts/code.json

+    "description": "The label used to tell the user that he's browsing an unmaintained doc version"
+  },
+  "theme.docs.versions.latestVersionSuggestionLabel": {
+    "message": "We recommend you use the {latestVersionLink} ({versionLabel}).",


In technical writing:

Avoid first-person pronouns. Details see Pulsar Documentation Writing Style Guide.

Avoid using "recommend" if possible. A phrase such as “We recommend that you take the following action” could create a potential marketing or legal problem. For how to write this tip, see fix docs banner text #207 (comment).

urfreespace · 2022-09-08T11:55:14Z

@Anonymitaet @tisonkun Maybe we need to agree on the text and style of the banner

tisonkun · 2022-09-08T15:09:45Z

Hi @Anonymitaet

For the latest stable doc version (eg. 2.10.x):

This is the latest stable version 2.10.x.

I don't think we need a banner for the (expected) latest stable doc.

Agree on other wording changes.

Blue is more appropriate than yellow/red here.

Yellow / red can be used to indicate important hints, tips, guidance, restrictions, advice that might be overlooked, or the possibility of damage to software.

If yellow / red is overused, they lose their significance.

Here we'd like to hint the users to use the latest stable doc. So it's not overuse from my perspective. You can get the image why it's a hint from:

You can find several projects that don't follow this way. But think of the Pulsar situation - we don't maintain quite a few old versions, and it's still under rapid development. We don't want users to use an old version and ask for bug fixes cherry-pick, but just try out the latest stable. For users already use an old version, the color is not a big deal.

Anonymitaet · 2022-09-09T02:50:32Z

@tisonkun thanks!

Since the Pulsar website background is light blue, yellow / red is too obvious on light blue than it is on the white background (eg. Docusaurus).

tisonkun · 2022-09-09T03:17:12Z

@Anonymitaet I agree that color is hard 🤣 The comment here is to make it relatively obvious, but choosing a nice color can be improved later. @labuladong @Sepush do you have some input on which color is suitable for this purpose?

Sepush · 2022-09-09T03:40:30Z

@Anonymitaet I agree that color is hard 🤣 The comment here is to make it relatively obvious, but choosing a nice color can be improved later. @labuladong @Sepush do you have some input on which color is suitable for this purpose?

I recommend don't use blue as the background just use white for light mode, If you want blue theme,only apply for the link border or some others will be better

tisonkun · 2022-09-09T04:07:24Z

don't use blue as the background just use white for light mode

This is a pivotal change. Let's stop further discussion in this direction.

michaeljmarshall · 2022-09-09T04:35:50Z

I like the banner for the next docs, thank you for proposing this change @Anonymitaet!

michaeljmarshall · 2022-09-09T04:37:30Z

I'm not sure where to provide this feedback (so feel free to redirect me to a different channel), but I find the recent change to version numbers being 2.10.x to be confusing. I like to know that I am looking at the exact documentation for a version, since there are minor changes between patch versions that might affect documentation. Without explicit versioning, we lose important nuance.

labuladong · 2022-09-09T06:29:00Z

@Anonymitaet I agree that color is hard 🤣 The comment here is to make it relatively obvious, but choosing a nice color can be improved later. @labuladong @Sepush do you have some input on which color is suitable for this purpose?

I think yellow is fine, we can make it darker if light yellow is too obvious on light blue.

labuladong · 2022-09-09T06:33:33Z

I'm not sure where to provide this feedback (so feel free to redirect me to a different channel), but I find the recent change to version numbers being 2.10.x to be confusing. I like to know that I am looking at the exact documentation for a version, since there are minor changes between patch versions that might affect documentation. Without explicit versioning, we lose important nuance.

Hi @michaeljmarshall, could this Other button solve your problem? That page lists all versions:

momo-jun · 2022-09-09T06:49:00Z

I'm not sure where to provide this feedback (so feel free to redirect me to a different channel), but I find the recent change to version numbers being 2.10.x to be confusing. I like to know that I am looking at the exact documentation for a version, since there are minor changes between patch versions that might affect documentation. Without explicit versioning, we lose important nuance.

@michaeljmarshall you can refer to PIP-190 for more details. In short, the changes between patch versions are annotated with a version-specific note like “This configuration is only available in 2.10.1 and later versions.”

tisonkun · 2022-09-10T08:57:53Z

That page lists all versions:

Unfortunately, it doesn't. It still lists one 2.10.x entry for all 2.10.x series versions.

This is a separate topic, I suggest you start another thread to discuss it.

tisonkun · 2022-09-10T09:00:54Z

@Anonymitaet @urfreespace improving color can be a continuous effort. If we now agree on the wording part. We can push forward the changes in wording.

I have one comment here: Don't show a banner for the latest stable version. Users are already on the version we'd recommend and nothing should be noticed.

Anonymitaet · 2022-09-13T01:41:34Z

@tisonkun Thanks!
I'd still prefer to keep the banner on the latest stable version to keep the behavior consistent, so that users may not wonder why "this page does not have such info while others pages have", then they may stop for a while to think about it. What users want s "Do not make me think, I want to skim and scan info quickly".

momo-jun · 2022-09-14T02:35:21Z

My personal opinion on the banner:

Keep the current blue background color for the banner to minimize the effort. It's just a notification, not a striking/breaking change, and doesn't need highlights/cosmetics.
No show the banner for the latest stable version of the doc, to eliminate noise for those who're already looking at the right docs. They don't even have to think, because they are possibly unaware of the banner behavior for other versions of docs.

urfreespace · 2022-09-19T01:51:29Z

As the new text is more explicit and precise so update the text from this Pr and keep the background color blue, are you all agree? @Anonymitaet @tisonkun @momo-jun /cc @tuteng

Signed-off-by: Li Li <urfree@apache.org>

urfreespace · 2022-09-19T06:16:45Z

I will merge it if there are no objections before 5:00 p.m @Anonymitaet @momo-jun

Anonymitaet · 2022-09-19T07:29:20Z

@urfreespace Let's make a compromise and consensus on this:

☘️☘️☘️ Banner wording

Remove the banner for the latest stable version.

🔹🔹 🔹

For Next docs:

This is unreleased documentation for Next.
For the latest stable version, see 2.10.x.

🔹🔹 🔹

~~For the latest stable doc version (eg. 2.10.x):~~

~~This is the latest stable version 2.10.x.~~

🔹🔹 🔹

For docs in the maintenance cycle (eg. 2.9.x, 2.8.x):

This is the documentation for 2.9.x
For the latest stable version, see 2.10.x.

🔹🔹 🔹

For docs not in the maintenance cycle (eg. versions prior to 2.8.x):

This is the documentation for 2.6.2, which is no longer actively maintained.
For the latest stable version, see 2.10.x.

☘️☘️☘️ Banner color

Blue

urfreespace · 2022-09-19T08:09:51Z

@urfreespace Let's make a compromise and consensus on this:

☘️☘️☘️ Banner wording

Remove the banner for the latest stable version.

🔹🔹 🔹

For Next docs:

This is unreleased documentation for Next.
For the latest stable version, see 2.10.x.

🔹🔹 🔹

~~For the latest stable doc version (eg. 2.10.x):~~

~~This is the latest stable version 2.10.x.~~

🔹🔹 🔹

For docs in the maintenance cycle (eg. 2.9.x, 2.8.x):

This is the documentation for 2.9.x
For the latest stable version, see 2.10.x.

🔹🔹 🔹

For docs not in the maintenance cycle (eg. versions prior to 2.8.x):

This is the documentation for 2.6.2, which is no longer actively maintained.
For the latest stable version, see 2.10.x.

☘️☘️☘️ Banner color

Blue

Unreleased version banner

Maintained version banner

Unmaintained version banner

Signed-off-by: Li Li <urfree@apache.org>

momo-jun · 2022-09-19T08:46:40Z

@urfreespace @Anonymitaet can we remove the banner from this page?

Anonymitaet · 2022-09-19T08:52:01Z

@urfreespace @Anonymitaet can we remove the banner from this page?

sure

fix docs banner text

90822b4

Signed-off-by: Li Li <urfree@apache.org>

urfreespace requested a review from Anonymitaet September 8, 2022 07:48

urfreespace self-assigned this Sep 8, 2022

urfreespace marked this pull request as ready for review September 8, 2022 07:48

urfreespace mentioned this pull request Sep 8, 2022

Version banner in docs pages #204

Merged

urfreespace requested a review from momo-jun September 8, 2022 07:50

urfreespace added 2 commits September 8, 2022 15:55

update

15f544b

Signed-off-by: Li Li <urfree@apache.org>

update

fae4c5c

Signed-off-by: Li Li <urfree@apache.org>

momo-jun reviewed Sep 8, 2022

View reviewed changes

tisonkun requested changes Sep 8, 2022

View reviewed changes

Anonymitaet reviewed Sep 8, 2022

View reviewed changes

Anonymitaet mentioned this pull request Sep 8, 2022

Generate client config docs from source code #176

Merged

tisonkun approved these changes Sep 19, 2022

View reviewed changes

update

cc01984

Signed-off-by: Li Li <urfree@apache.org>

Anonymitaet mentioned this pull request Sep 19, 2022

[Doc] Add prompt to users who are reading old version doc apache/pulsar#17501

Closed

2 tasks

update

02bb6c0

Signed-off-by: Li Li <urfree@apache.org>

Anonymitaet approved these changes Sep 19, 2022

View reviewed changes

urfreespace merged commit e8635a6 into main Sep 19, 2022

urfreespace deleted the update-docs-banner-texts branch September 30, 2022 02:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix docs banner text #207

fix docs banner text #207

urfreespace commented Sep 8, 2022 •

edited

Loading

momo-jun Sep 8, 2022

tisonkun Sep 8, 2022

tisonkun Sep 8, 2022

tisonkun Sep 8, 2022

Anonymitaet commented Sep 8, 2022 •

edited

Loading

Anonymitaet Sep 8, 2022 •

edited

Loading

urfreespace commented Sep 8, 2022

tisonkun commented Sep 8, 2022

Anonymitaet commented Sep 9, 2022

tisonkun commented Sep 9, 2022

Sepush commented Sep 9, 2022

tisonkun commented Sep 9, 2022

michaeljmarshall commented Sep 9, 2022

michaeljmarshall commented Sep 9, 2022

labuladong commented Sep 9, 2022

labuladong commented Sep 9, 2022

momo-jun commented Sep 9, 2022

tisonkun commented Sep 10, 2022

tisonkun commented Sep 10, 2022

Anonymitaet commented Sep 13, 2022

momo-jun commented Sep 14, 2022

urfreespace commented Sep 19, 2022 •

edited

Loading

urfreespace commented Sep 19, 2022

Anonymitaet commented Sep 19, 2022

urfreespace commented Sep 19, 2022 •

edited

Loading

momo-jun commented Sep 19, 2022

Anonymitaet commented Sep 19, 2022

	"This documentation is for an unreleased {siteTitle} {versionLabel} version of Apache Pulsar. "
	"This documentation is for an unreleased version of Apache Pulsar. "

	"This documentation is for an out-of-date {siteTitle} {versionLabel} version of Apache Pulsar. "
	"This documentation is for an out-of-date version of Apache Pulsar. "

fix docs banner text #207

fix docs banner text #207

Conversation

urfreespace commented Sep 8, 2022 • edited Loading

Unreleased version banner

Maintained version banner

Unmaintained version banner

momo-jun Sep 8, 2022

Choose a reason for hiding this comment

tisonkun Sep 8, 2022

Choose a reason for hiding this comment

tisonkun Sep 8, 2022

Choose a reason for hiding this comment

tisonkun Sep 8, 2022

Choose a reason for hiding this comment

Anonymitaet commented Sep 8, 2022 • edited Loading

Anonymitaet Sep 8, 2022 • edited Loading

Choose a reason for hiding this comment

urfreespace commented Sep 8, 2022

tisonkun commented Sep 8, 2022

Anonymitaet commented Sep 9, 2022

tisonkun commented Sep 9, 2022

Sepush commented Sep 9, 2022

tisonkun commented Sep 9, 2022

michaeljmarshall commented Sep 9, 2022

michaeljmarshall commented Sep 9, 2022

labuladong commented Sep 9, 2022

labuladong commented Sep 9, 2022

momo-jun commented Sep 9, 2022

tisonkun commented Sep 10, 2022

tisonkun commented Sep 10, 2022

Anonymitaet commented Sep 13, 2022

momo-jun commented Sep 14, 2022

urfreespace commented Sep 19, 2022 • edited Loading

urfreespace commented Sep 19, 2022

Anonymitaet commented Sep 19, 2022

urfreespace commented Sep 19, 2022 • edited Loading

Unreleased version banner

Maintained version banner

Unmaintained version banner

momo-jun commented Sep 19, 2022

Anonymitaet commented Sep 19, 2022

urfreespace commented Sep 8, 2022 •

edited

Loading

Anonymitaet commented Sep 8, 2022 •

edited

Loading

Anonymitaet Sep 8, 2022 •

edited

Loading

urfreespace commented Sep 19, 2022 •

edited

Loading

urfreespace commented Sep 19, 2022 •

edited

Loading