Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DO NOT MERGE] Prototype: archived versions, the main end #2128

Closed
wants to merge 6 commits into from

Conversation

pepopowitz
Copy link
Collaborator

@pepopowitz pepopowitz commented May 19, 2023

What is the purpose of the change

Demonstrates the "active docs" end of #1173. See #2129 for the "archived version" end.

This PR won't be merged, but it serves to provide actual code for a review of the approach & details.

What's happening on the "active docs" end?

  • Archived versions are not built in this site. In the real implementation, we could remove the source for all archived versions.

  • Rewrite rules are updated to send all 1.3 requests to the archived 1.3 website.

  • A link is added to the navbar for each archived version:

    image

Clarifying comments will also be added in-line.

A video demonstrating the relationship between this and the active docs

An updated recording is at https://www.loom.com/share/e8d5c9d736554f71b66bbcf774de09e0

@pepopowitz pepopowitz added the hold This issue is parked, do not merge. label May 19, 2023
Comment on lines 92 to 95
{
label: "1.3",
href: "https://1_3.docs.camunda.io",
},
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We will introduce these one at a time, as each version is archived.

@@ -113,7 +113,7 @@ RewriteRule ^docs/apis-clients(.*)$ /docs/apis-tools$1 [R=301,L]
RewriteRule ^optimize/apis-clients(.*)$ /optimize/apis-tools$1 [R=301,L]
RewriteRule ^docs/8.0/apis-clients(.*)$ /docs/8.0/apis-tools$1 [R=301,L]
RewriteRule ^optimize/3.8.0/apis-clients(.*)$ /optimize/3.8.0/apis-tools$1 [R=301,L]
RewriteRule ^docs/1.3/apis-clients(.*)$ /docs/1.3/apis-tools$1 [R=301,L]
# RewriteRule ^docs/1.3/apis-clients(.*)$ /docs/1.3/apis-tools$1 [R=301,L]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'll let the 1.3 website handle any of these page-specific redirects...

static/.htaccess Outdated
Comment on lines 509 to 510
## extract version 1.3/optimize 3.7.0:
# RewriteRule ^docs/1.3/(.*)$ https://1_3.docs.camunda.io/docs/$1 [R=301,L]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

...and just send all 1.3 traffic over to that new site.

@@ -1 +1 @@
["3.10.0", "3.9.0", "3.8.0", "3.7.0"]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Associated with this change would be the removal of all optimize 3.7.0 docs from this branch.

@@ -1 +1 @@
["8.2", "8.1", "8.0", "1.3", "1.2", "1.1", "1.0", "0.26", "0.25"]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Associated with this change would be the removal of all archived docs from this branch.

@akeller
Copy link
Member

akeller commented May 22, 2023

We are 100% aligned here.

  • We need to confirm with Product Management what we call the "Archived" versions. We use terms like "unsupported" or "unmaintained," which may work better here. I can follow up on this.
  • It's redundant to put the version in the subdomain and URL, just one place is fine.
  • Visually, we'll need to add something to clarify that this is an "Archived" version. Quick win would be to use the banner and add a link to the current docs. We don't need to do any significant heavy lifting like changing the styles.

Do you need any additional help or feedback from me?

{
type: "html",
className: "dropdown-archived-versions",
value: "<b>Archived versions</b>",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Internally, I've asked PM for feedback on what to call this. I'll also follow up in the C8 Stakeholder meeting.

akeller
akeller previously approved these changes May 22, 2023
@pepopowitz
Copy link
Collaborator Author

pepopowitz commented May 22, 2023

  • Visually, we'll need to add something to clarify that this is an "Archived" version. Quick win would be to use the banner and add a link to the current docs. We don't need to do any significant heavy lifting like changing the styles.

Oh yeah, good catch! This is the current banner for 1.3 docs -- is it sufficient to show this on all the individual doc pages, and not show anything on the 1.3 "home" page?

image

Do you need any additional help or feedback from me?

I don't think so!

@akeller
Copy link
Member

akeller commented May 22, 2023

Oh yeah, good catch! This is the current banner for 1.3 docs -- is it sufficient to show this on all the individual doc pages, and not show anything on the 1.3 "home" page?

image

I realized I've committed the ultimate code review sin by scattering my feedback everywhere 😬 (across two PRs, but it feels like a lot more). SORRY! I think you are following me, though, so thank you!

  • Keep the banner on the individual doc pages.
  • Remove the Sign Up banner across the top of the nav.

IMO, this is sufficient.

However, trying to put my forward-looking hat on, how can we further save people from themselves if they end up in the archived area?

We could use what's currently the Sign Up banner across the top of the nav with a different color that points to docs.camunda.io and tells people very clearly that this is an old version. This would cover the gap on the homepage, contact page, etc. and we wouldn't need to worry about repointing it anywhere for the latest numbered version.

announcementBar: {
      id: "unsupported",
      content:
        '🚨 These docs are unsupported and unmaintained. Looking for <b><a target="_blank" rel="noopener noreferrer" href="https://docs.camunda.io">supported versions?</a></b> 🚨',
      backgroundColor: "#FFC600",
      textColor: "#434343",
      isCloseable: false,
    },

It's not closeable (incognito test if you, like me, closed it at some point), and the colors are on brand. Text and emoji could be changed, but it's something.

// ([versionName]) => ({
{
label: "1.3",
href: "https://unsupported.docs.camunda.io/1.3/",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These URLs have been updated recently -- we'll put all archived versions in the same subdomain, but each one will have its own path on that server.

# RewriteRule ^docs/1.3/self-managed/optimize-deployment/(.*)$ /optimize/3.7.0/self-managed/optimize-deployment/$1 [R=301,L]

## extract version 1.3/optimize 3.7.0:
RewriteRule ^docs/1.3/(.*)$ https://unsupported.docs.camunda.io/1.3/docs/$1 [R=301,L]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the rule that sends all 1.3 traffic over to that archived site.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very clean and nice!

akeller
akeller previously approved these changes May 26, 2023
@pepopowitz
Copy link
Collaborator Author

Closing this, as the work is starting to happen.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
hold This issue is parked, do not merge.
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

2 participants