crossplane / docs Goto Github PK

Currently, docs the use an h4 element render it larger than an h3 because the h1 / h2 / h3 elements have CSS overridden in https://github.com/crossplane/crossplane.github.io/blob/5c829b27fdb41fe4a1212e6a0eb63c989ae7d3e0/css/docs.scss#L34, while h4 does not so it falls back to https://github.com/crossplane/crossplane.github.io/blob/5c829b27fdb41fe4a1212e6a0eb63c989ae7d3e0/css/main.scss#L83. h4 should also be added to docs.scss.

Example (Manifests and Configurations are h3 while Motivation is h4):

cc @thephred

The crossplane.io website should publicly state that it is a CNCF project, as per the website guidelines. Specific requirement:

Sandbox-level projects should include the sentence “We are a Cloud Native Computing Foundation sandbox project.” and the CNCF logo

You can see a similar example from rook.io near the bottom, like so:

Of course, that's a bit different since Rook is past the sandbox now, so please use the required text from above 🙇‍♂️

What problem are you facing?

I have been going through the Crossplane Stacks Guide, and I am noticing that the browser window's title is set to "Crossplane Docs", even though I am looking at the stacks guide. I am thinking that if I am a user searching on the internet for Crossplane Stacks, having the title as something more like "Crossplane Stacks Guide" or "Crossplane Docs | Stacks Guide" would be helpful for having the stacks guide appear near the top of the search results.

If we did this, it seems like it is a pattern that we would want to apply for all pages.

How could Crossplane help solve your problem?

Set titles on the Crossplane Docs pages that match their individual content, instead of having the same title for every page.

We should host this website on Netlify like we do with other sites.

From within a page in the documentation, when the selected version is changed the result is the default homepage doc for the newly selected version. It would be nice if we retained the current docs page that the user was on instead of making them navigate to it again.

For example, when on https://crossplane.io/docs/v0.1/cloud-providers.html and I select "master", I am taken to https://crossplane.io/docs/master/. I expect to be taken to the master version of the same doc I was already on, i.e. https://crossplane.io/docs/master/cloud-providers.html.

I frequently find myself searching for specific terms in our documentation, but end up just coming back to searching the source in c/c because there is not an efficient way to do so on the site itself.

This keeps coming up even when I accept it.

Setting up Network Policies for applications deployed on (for example: EKS) kubernetes clusters is a typical security requirement.
Instead of attempting to reverse engineer the Egress and Ingress paths that Crossplane might need to function, a guideline must be provided in some part of Crossplane documentation.

I noticed that though the popsicle twitter card will render for links to crossplane.io, it will not render for links to specific pages. Example can be seen here.

Currently we need to keep all documentation we want on the website (including API type documentation) in the core Crossplane repo, even when documenting stack resources. Ideally we'd support syncing docs folders from each stack to form one cohesive set of documentation.

Reported by @bassam

Here is how my experience looks like:

• Enter crossplane.io
• Click to CTA button, go to Github repo.
• See the following

Then click Getting Started which takes you to getting started page markdown in Github. It lets you install Crossplane but that's pretty much it. You have to go back and click specifically Docs in the README to get the full getting started flow experince.

I'd like to suggest considering CTA button to take you to Docs page directly for a curated experience as the first impression or include the quick start in README of the Github repo so that people don't have to go back and forth between pages. When I visit projects, I especially like when the quick start is easy to access for a quick trial.

There is currently significant work being done on the Equinix Metal Provider and Equinix Metal should be included on our landing page 🚀

/cc @displague

We have the following text on crossplane.io that is intended to introduce the "Adopters" section:

Started by Upbound and adopted by the cloud native community

This is information similar to what was included in the original CNCF sandbox proposal.

While do have the official wording required by the CNCF website guidelines, we can add some clarification about the Sandbox status this will help address confusion that is happening within the CNCF ecosystem.

Let's update this text to:

Started by Upbound and adopted as a sandbox project by the cloud native community

This looks like a similar issue to #14, where the Jekyll processing isn't handling certain markdown correctly.

See step 7 on https://crossplane.io/docs/master/workloads/aws/wordpress-aws.html#create-your-amazon-eks-cluster-vpc and the attached screenshot, where the codeblock (triple backticks) aren't being rendered correctly.

Note this renders OK in the github repo: https://github.com/crossplaneio/crossplane/blob/master/docs/workloads/aws/wordpress-aws.md#create-your-amazon-eks-cluster-vpc

are we able to exclude old version content from being indexed at Google?

Searching for "crossplane aws rds" should not result in crossplane v0.3 being the first link.

One of the final steps for onboarding Crossplane into the CNCF (cncf/toc#466) is to add the required footer to the crossplane.io website.

We did this recently on https://rook.io/ in https://github.com/rook/rook.github.io/pull/90/files. Use that PR as a reference for the content that should be added to crossplane.io in a footer, obviously using the crossplane.io styling though 😎

Headings throughout the docs do not offer a link. Inspecting the document reveals than an id attribute is present on headings but there is no linking aid available.

For example: https://crossplane.io/docs/v0.3/services-developer-guide.html#getting-started

I would expect a chain-link icon to appear when hovering over this title and I would expect that I could click that icon to have the link copied.

I would settle for the ability to right click on the heading or a linking aid and choose to copy the link that way.

Crossplane has made a ton of progress since 0.2, so the crossplane.io website need to be updated to match. Enable users to rapidly understand Crossplane, get started, and find the information they're looking for.

Part of the 0.3 release

What seems to be the problem?

Crossplane has made a ton of progress since 0.2 and the crossplane.io website needs to be updated to reflect the 0.3 enhancements, reflect the updated roadmap & vision, and make it easier for new users & contributors to get started.

What could Crossplane do to help?

Our current thinking is that the crossplane.io website should be updated:.

• Use the consistent language from crossplane/crossplane#636
• Curated content updated to reflect the 0.3 release
• Align with crossplane/README.md focused on new user eval and on-boarding UX:
  • evaluate if Crossplane will solve your problems in < 1 min
  • get started with Crossplane in < 5 minutes
• Align with ROADMAP.md is updated to reflect 0.3, 0.4, and 0.5 releases through end of 2019
  • understand the current and future state of the project at a high-level in < 2 minutes, so they can quickly learn using the links from crossplane.io to GitHub, Slack, etc.
• updated to reflect the refined project vision and planned 2019 content

What does it look like when we're done?

The user understands the problems Crossplane is solving, if it's applicable to them, and how to get started as a new user or contributor, without having to worry about sifting through content which is not relevant.

• Terms are defined, consistently used, and the definitions are easy to find
• The documentation reflects the 0.3 release
• Unnecessary content has been removed
• User scenarios (such as getting started) should be well-documented, easy to find, and brief, including:
  • Evaluating Crossplane for a user's use-case
  • Getting started with Crossplane
  • Evaluating and consuming infra stacks (including comparing infra stack capabilities and maturity)
• Update content to reflect of past, present, and planned future directions, so they're easily understood at a high level in under 2 minutes
• Add a link to the YouTube channel (https://www.youtube.com/channel/UC19FgzMBMqBro361HbE46Fw) from crossplane.io

How can we demonstrate this?

• Visit crossplane.io and get a updated high-level overview of the project, click GitHub, Slack for more info

Related

• Use ubiquitous language from crossplane/concepts.md as updated in crossplane/crossplane#636
• Align with crossplane/roadmap.md crossplane/crossplane#637
• TBD: Updated v0.3 copy for crossplane.io
• TBD: Update website content with new copy, graphics, etc.

When we want to add a link to a specific doc in another doc, we have to embed a version in the rule. We can use master as version but that links to RC and throws a big red warning box.

Being able to simply provide the link to the doc with latest or no version in url at all would be useful.

I've seen in other docs sites the ability to have an auto generated "table of contents" for every page. This can really help navigate on longer pages that have lots of content and therefore lots of scrolling. Having a per page TOC can help jump to a specific section right way and generally navigate the long wall of text more easily.

An example page where this would be really helpful is the composition reference page: https://crossplane.io/docs/v1.4/reference/composition.html

An example from the CockroachDB docs can be found here: https://www.cockroachlabs.com/docs/stable/make-queries-fast.html

Note that the "On this page" TOC scrolls along with the page, so it's always accessible, and the current section of the docs is highlighted within the TOC to give a clue as to your current location. This is super helpful for navigation and would help the Crossplane docs too!

With the redirect_to directives in the API Documentation e.g. from https://crossplane.io/docs/v1.4/api-docs/overview.html to https://crossplane.io/docs/v1.4/api-docs/crossplane.html a user can't navigate back anymore.

We don't yet have a page which explains the Crossplane governance model or Upbound's commitment to open source. Until we have that, we should remove this line since we have nothing to link to.

GitHub Dependabot alerts suggest we update nokogiri and commonmarker.

We have a security alert that suggests we "Upgrade kramdown to version 2.3.0 or later". Will do a pass on the deps and get things updated.

Registration banner still is present on the website despite the link not being functional.

Looks like we missed updating the messaging in the twitter metadata:

 <meta name="twitter:description" content="Manage your applications and infrastructure the Kubernetes way" />

Can we update this to the same as the big page headline?

Manage any infrastructure your applications need directly from Kubernetes

What problem are you facing?

In crossplane/crossplane#2919 , we mention users can enable wehbooks in Helm parameter reference but that's not very visible.

How could Crossplane help solve your problem?

We should mention this and other alpha features more clearly in the installation steps.

The links in https://crossplane.io/docs/v1.4/getting-started/install-configure.html#start-with-a-hosted-crossplane appear to be broken for create and connect:

you can create and then connect to your hosted Crossplane cluster.

This is what the links currently point to:
Create: https://cloud.upbound.io/docs/getting-started/set-up-upbound-cloud
Connect: https://cloud.upbound.io/docs/getting-started/connect-to-your-platform

We should figure our more recent and better targets for these links, and get them updated. Also worth backporting to previous docs versions.

What problem are you facing?

The banner on crossplane.io still mentions KubeCon EU '21.

How could we address your issue?

The banner could instead say:
Crossplane is now a CNCF Incubating Project <LINK> and link to https://blog.crossplane.io/crossplane-cncf-incubation/

Crossplane.io - documentation

Defaults to "Crossplane v0.2 latest" in the pull down menu

Most docs have been updated in Master

When you select master you get a red warning box that is off putting

Suggestion is to:

1. Remove the warning box
2. Make the default the latest docs (not sure if we call that master or give it a generic name, like "latest" if master is off-putting
3. Tag the docs in master with the TOC/positon information eg (https://images.zenhubusercontent.com/5cd3396068f236637fc7f614/c3da11cb-dfb6-4169-af17-0779cdae8b9e)

The goal is for the documentation menu dropdown to default to the latest, have those docs auto-reference from master, without the warning screens.

In exploring the issue, some documentation links are broken.

For example, on this page: https://crossplane.io/docs/master/workloads/gcp/wordpress-gcp.html
when you click "Edit on Github" it goes to: https://github.com/crossplaneio/crossplane/blob/master/docs/wordpress-gcp.md
but should go to: https://github.com/crossplaneio/crossplane/blob/master/docs/workloads/gcp/wordpress-gcp.md

The cookie banner at https://crossplane.io/ obscures the site navigation.

(separately: the banner as it stands is not really useful as the site sets cookies to people who do consent and to people who don't consent)

We need to add a twitter card to the website.

The website lacks IPv6 support.
Since it seems to use CloudFront, fixing this should be as easy as enabling IPv6 on the CloudFront distribution and creating an AAAA ALIAS record pointing to it.

What problem are you facing?

As Crossplane becomes increasingly popular, community members around the world are presenting about it at company brown bags, cloud-native meetups, and workshops they might do at conferences. It would be awesome if the Crossplane community were able to know about these events through an easy and intuitive self-reporting mechanism. That way the community could amplify these talks through social media and support the presenters with SWAG.

How could Upbound help solve your problem?

There could be a page on crossplane.io linked to from the header which includes a form that community members can submit and make us aware of talks they're doing by adding them to a shared Google Calendar.

Currently when a user goes to either master or a previous version of the docs a banner informs them they are not looking at the latest version's documentation. However, the alert could stand to be a bit more alarming as the current one does not really feel like a deterrent to reading older docs.

What problem are you facing?

Crossplane is able to provision infrastructure through infra-stacks and schedule applications through app-stacks (or directly via workload scheduler).

The users who decide to go with Crossplane have a number of different setups and AFAIK the combination of Terraform and Helm is one of the most popular ones. For Helm, we have the template stacks work going on which would allow a helm chart to be used directly. However, users do not have a guide/script for migrating from Terraform to Crossplane infra stacks.

How could Crossplane help solve your problem?

A guide that explains how Terraform setups could be migrated with examples could be useful for users to easily migrate as well as see what their setup would look like before deciding.

When opened a link to a crossplane blog (e.g. this post), one should be able to navigate the the main site (https://crossplane.io), possibly by having an option in the menu bar.

our version selector is on the top right.

What problem are you facing?

When users google for documentation, they're taken to out of date docs pages much of the time.

What could we do to make it better?

Today there's a banner at the top of a page which is out of date informing users the docs are old. However, as users scroll down the page or link to a specific header, that banner doesn't appear.

This banner could be sticky and scroll with the user so it's always visible and clear that users are viewing old and out of date documentation.

What problem are you facing?

In crossplane/crossplane#2919 , we mention users can enable wehbooks in Helm parameter reference but that's not very visible.

How could Crossplane help solve your problem?

We should mention this and other alpha features more clearly in the installation steps.

The code block at the end of the GCP Wordpress workload docs is rendered incorrectly on the docs site, but it is OK in the Github docs, leading me to believe that something is wrong with the Jekyll processing, or site's CSS, or something. The markdown as committed in the source code tree is OK I think.

See the incorrect rendering at this link:
https://crossplane.io/docs/v0.1/workloads/gcp/wordpress-gcp.html#clean-up

Bad docs site screenshot:

See the OK rendering on the Github docs:
https://github.com/crossplaneio/crossplane/blob/master/docs/workloads/gcp/wordpress-gcp.md#clean-up

OK github docs screenshot:

What problem are you facing?

https://github.com/crossplane/crossplane/blob/master/design/design-doc-rbac-manager.md

We've had the Crossplane RBAC manager for a long time (since before 1.0) but it has never been documented, as far as I can tell.

How could Crossplane help solve your problem?

Document it! I wrote it so I should probably do this. :)

I'm experimenting with autogenerating API documentation for Crossplane using https://github.com/negz/crossdocs. Most of our website seems to be generated from markdown, so that's what I output. I'd like to use markdown tables, but these look unstyled in the HTML output:

As far as I can tell the markdown is being translated to a perfectly cromulent HTML <table>.

What problem are you facing?

We have the webhook capabilities in Crossplane but there isn't much documentation for people to see how they can implement it in their providers.

How could Crossplane help solve your problem?

We can update the provider development guide to have a section about webhooks.