New IA implementation

[chalin]

Reference: #110, #65

Permalink Structure

• Blog (/blog)
• Community (/community) Create a Community page #306
  • Contributor Guide (/docs/contributor-guide) -- either as a separate page or embedded in Community Create Contributor Guide #400
    • Issue Triage Guidelines (/docs/contributor-guide/issues)
    • Reporting bugs (/docs/contributor-guide/reporting_bugs)
• Docs (/docs Documentation ToC)
  • v3.5† (docs/v3.5) #363
    • Administration (/docs/v3.5/administration) Create Administration page #401
    • Quickstart (/docs/v3.5/quickstart) Getting Started #218, Quickstart page for etcd #278
    • Install (/docs/v3.5/install) Install page: create from reworked download-and-build #318
    • Troubleshooting etcd (/docs/v3.5/troubleshooting) Create a "Troubleshooting etcd" page  #395
    • Overview (/docs/v3.5/rfc/v3api/) #364
    • Demo (/docs/v3.5/demo) (Rework into Tutorials section) Consider reworking "Demos" page into "Tutorials" #402
    • Download and build (docs/v3.5/dl-build) (Refactor into Quickstart and Installation) Rename docs/next/dl-build to install #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) Create Contributor Guide #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) Consider reworking "Demos" page into "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) (Convert Platforms/Amazon Web Services page into a blog post #396, Convert "Platforms/Container Linux with systemd" page into a blog post #397, Convert "Platforms/FreeBSD" page into a blog post #398, Convert @marifse's Platforms/IBM PR into a blog post #399)
      • ⋮
    • Triage (/docs/v3.5/triage)
      • Issue Triage Guidelines (/docs/v3.5/triage/issues) Create Contributor Guide #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:

• Top nav, see New top-nav (for matching new IA) #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"):

• 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"
• 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.
• Consider the shorter name "Get started" rather than "Getting started"
• 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 #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 #280 (comment)

[nate-double-u]

• We should add a "Getting Started with etcdctl" page (Create a "Getting started with etcdctl" page #394) to the new infrastructure as it was specifically asked for in issue Etcd.io Docs/SEO Improvement Plan #65.

[nate-double-u]

• We should add a Write "Troubleshooting etcd" page (Create a "Troubleshooting etcd" page  #395) to the new infrastructure as it was specifically asked for in issue Etcd.io Docs/SEO Improvement Plan #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 #309 (comment):

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