search

etcd-io / website

etcd.io
https://etcd.io
Other
145 stars 293 forks source link

New IA implementation #267

Open chalin opened 3 years ago

chalin commented 3 years ago

Reference: #110, #65

Permalink Structure

Legend

Bold: new pages Italic: moved pages (new location) Strike through: moved or removed pages (old location) ⋮ (vertical ellipsis): one or more unlisted pages

Notes

† v3.5 expanded as an example. v3.5 and v3.4 currently share the same architecture, but may differ in future. ‡ Content under Platforms should be reworked and made into blog posts. (Amazon Web Services, Container Linux with systemd, FreeBSD)

Other:

chalin commented 3 years ago

@nate-double-u: good first pass. Here are some suggestions for the "sitemap" (which isn't really a sitemap -- maybe we should call it "Permalink structure"):

nate-double-u commented 3 years ago

Why would "Administration", "Get started", etc not be versioned?

Good question. I think I will move them under the versioning.

Also, what about pages like /docs/v3.4/triage(/issues), or /docs/v3.4/upgrades? Should they be removed from under versioning? I expect that the process of opening a ticket won't change from version to version. Upgrades is a list of X.Y to X.Z upgrades, so is mostly duplicated content.

nate-double-u commented 3 years ago

While we go through this process we should consider standardizing "-" vs "_" in links.

chalin commented 3 years ago

So in a nutshell, based on the reading of the docs I’ve done this week (05/09), here’s what I’m feeling needs to be done:

All of this is open to discussion, of course.

nate-double-u commented 3 years ago

I had initially tried to organize the IA into an Evaluation, Addition, Fix, and Features model; would a Concepts, Tasks, Tutorials, and Reference model (like on the k8s.io/docs pages) be a better model to go with given what we've got already built out?

nate-double-u commented 3 years ago

Sorry for the noise, but as this is a discussion about new pages and where and how to fit them in, I thought this would be a better place to discuss an Observability section.

From: #374:

An Observability section has been suggested during the conversations around the v3.5 release:

I wonder if it would make sense to have a section just for Observability in the navigation? To group metrics, profiling, logging and now tracing under there? https://etcd.io/docs/next/ @nate-double-u @chalin what do you think?

originally posted by @lilic in https://github.com/etcd-io/website/issues/280

I think we can add around https://github.com/etcd-io/website/blob/master/content/en/docs/next/op-guide/monitoring.md#prometheus as a section "Distributed tracing"?

have a section just for Observability in the navigation

I think once we have those in monitoring doc, we can discuss separating them out with @nate-double-u @chalin ?

Originally posted by @gyuho in https://github.com/etcd-io/website/issues/280#issuecomment-839537655

nate-double-u commented 3 years ago
nate-double-u commented 3 years ago

This may fit in well with the new Tutorials page/section.

nate-double-u commented 3 years ago

[edit] removing comment to refactor into issues like the above comments

chalin commented 3 years ago

There's some discussion of possible IA rework in https://github.com/etcd-io/website/issues/309#issuecomment-925412965:

Maybe /docs/v3.5/integrations/ should be split into the following (IMHO) more intuitive names especially if we bring in subpages:

  • /docs/v3.5/tools
  • ~/docs/v3.5/libraries~ ... /docs/v3.5/languages

Which makes me think that /docs/v3.5/platforms makes sense too.

Hmm, we have too many entries below /docs/v3.5.

chalin commented 3 years ago

@nate-double-u: is the original Jira ticket (associated with #65) still open? If not (or maybe regardless), opening a new ticket requesting an IA assessment and new IA proposal might make sense. WDYT? /cc @CelesteHorgan