New IA implementation

[chalin]

trafficstars

Reference: #110, #65

Permalink Structure

• [x] Blog (/blog)
• [x] Community (/community) #306
  • [ ] Contributor Guide (/docs/contributor-guide) -- either as a separate page or embedded in Community #400
    • [ ] Issue Triage Guidelines (/docs/contributor-guide/issues)
    • [ ] Reporting bugs (/docs/contributor-guide/reporting_bugs)
• [ ] Docs (/docs Documentation ToC)
  • [x] v3.5† (docs/v3.5) #363
    • [ ] Administration (/docs/v3.5/administration) #401
    • [x] Quickstart (/docs/v3.5/quickstart) #218, #278
    • [x] Install (/docs/v3.5/install) #318
    • [ ] Troubleshooting etcd (/docs/v3.5/troubleshooting) #395
    • [x] ~~Overview (/docs/v3.5/rfc/v3api/)~~ #364
    • [ ] ~~Demo~~ (/docs/v3.5/demo) (Rework into Tutorials section) #402
    • [x] ~~Download and build~~ (docs/v3.5/dl-build) (Refactor into Quickstart and Installation) #319
    • [ ] FAQ (/docs/v3.5/faq)
    • [ ] Branch management (/docs/v3.5/branch_management)
    • [ ] Libraries and tools (/docs/v3.5/integrations)
    • [ ] Metrics (/docs/v3.5/metrics)
    • [ ] ~~Reporting bugs~~ (/docs/v3.5/reporting_bugs) #400
    • [ ] Tuning (/docs/v3.5/tuning)
    • [ ] Discovery service protocol (/docs/v3.5/dev-internal/discovery_protocol)
    • [ ] etcd release guide (/docs/v3.5/dev-internal/release)
    • [ ] Logging conventions (/docs/v3.5/dev-internal/logging)
    • [ ] Learning (/docs/v3.5/learning)
      • [ ] ⋮
    • [ ] Tutorials (/docs/v3.5/tutorials) #402
      • [ ] ⋮
    • [ ] Developer Guide (/docs/v3.5/dev-guide)
      • [ ] ⋮
    • [ ] Operations Guide (/docs/v3.5/op-guide)
      • [ ] ⋮
    • [ ] Benchmarks (/docs/v3.5/benchmarks)
      • [ ] ⋮
    • [ ] Upgrading (/docs/v3.5/upgrades)
      • [ ] ⋮
    • [ ] ~~Platforms~~‡ (/docs/v3.5/platforms) (#396, #397, #398, #399)
      • [ ] ⋮
    • [ ] ~~Triage~~ (/docs/v3.5/triage)
      • [ ] ~~Issue Triage Guidelines~~ (/docs/v3.5/triage/issues) #400
  • [ ] ⋮ (versions 2.3 & 3.1-3.4)

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:

• [x] Top nav, see #341
• [ ] Homepage: adjustments to be done based on the IA implementation detailed above.

[chalin]

@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"):

• [x] Drop the "homepage" node, and left-shift all entries below it. We know everything is rooted below the homepage, and besides, we have a separate section for discussing the "homepage"
• [x] Add the permalink path name to each node: e.g. Docs (/docs) -- yes, it's trivial for "Docs" but less so for entries below that.
• [x] Consider the shorter name "Get started" rather than "Getting started"
• [x] Why would "Administration", "Get started", etc not be versioned?

[nate-double-u]

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]

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

[chalin]

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:

• Finalize a Get started page (considering the ectd README version, possibly). Then link to that page from the homepage (which will mean that we need a v3.4 version)
• Consider (re-)writing an Installation page, maybe using the download/build page as a base (but remove the testing part -- we can direct folks to the get-started page). We might also want to add that to the top-nav
• Consider reworking the demos into tutorials
• Consider writing a Community page (and adding a link to it in the top-nav). The info can come from the etcd README, in particular.
• Consider adding a link to play.etcd.io to the homepage and/or top-nav

All of this is open to discussion, of course.

[nate-double-u]

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]

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]

• [ ] We should add a "Getting Started with etcdctl" page (#394) to the new infrastructure as it was specifically asked for in issue #65.

[nate-double-u]

• [ ] We should add a Write "Troubleshooting etcd" page (#395) to the new infrastructure as it was specifically asked for in issue #65

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

[nate-double-u]

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

[chalin]

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]

@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