search

etcd-io / website

etcd.io
https://etcd.io
Other
148 stars 297 forks source link

Etcd.io Docs/SEO Improvement Plan #65

Open jberkus opened 4 years ago

jberkus commented 4 years ago

I've been looking over the current etcd website and documentation, and feel that a refactor is warranted in order to improve them. Over the next few months, I plan to commit a significant part of my personal time to doing the below; I'm looking for the project's approval that these are all things that should get done. I also have the support of CNCF's web designer to help with this.

Objectives

To make etcd.io the primary destination for information about how to run, deploy, maintain, and scale etcd, both as a real resource and via search engines.

What's Working

The etcd documentation is automatically built based on the sources in the main development repository, so that we have regular updates when new versions are released. We have fully browesable per-version documentation that contains a lot of information about etcd code and internals.

What's Not Working

Currently etcd.io is often not the first hit when searching on common etcd tasks, such as "etcd setup", "how can I scale etcd", or "etcd troubleshooting". Instead, various random other pages are, some associated with our project (such as the CNCF blog) and some not (Rancher.com or Portworx pages). Importantly, because the most findable sources are not part of the official etcd documentation, the information on them is often out of date.

Part of the reason for this is that the existing documentation is not very browseable, and is structured in a way to give it poor SEO. It is also difficult for beginning users to find what they need. This is something that we can fix.

Improvement Plan

Short Term

Home Page Improvements

Add the following static pages to the website, linked off a section on the home page:

Each of these static pages will live in the website repo rather than docs; as much as possible they will be somewhat version-agnostic. All basics will be covered on the static page, with links off of them only for more in-depth review or unusual circumstances (e.g. "etcdctl kerberos authentication").

Documentation Content

Replace TOC for documentation navigation with one that makes more logical sense from a "user journey" point of view. This will be the same TOC displayed on the static page. At a top level, this would mean replacing the existing sections with the following:

Each section will be reworked so that it follows some kind of logical order, for example from installation, to growing the cluster, to upgrading. Note that this may require adding additional required header information into existing documentation files.

We also need to fix multi-version navigation. That is, switching "versions" of the documentation should automatically navigate to that page in the selected version of the docs, if that page exists. If this is challenging to do with the documentation toolchain we have, re-evaluate whether we want to keep versioned documentation.

Blog

Encourage weekly blog posts of unique content, mostly alternating how-to articles and release updates (patches, etc.). The new content here will drive some traffic as well as supply material for future documentation.

Cleanup

Fix 404s: we have a lot of lost pages. These need to get replaced with redirects. Shorten redirect chains (not sure how many of these we have) Add a Documentation tag to both the Etcd and Website repos so that we can start tracking docs issues.

Ongoing/Long Term

Blog Transfer

As we accumulate extra "How To" information into our blog, this content will be reworked in order to create a "Solutions" section for the documentation. This will be like the Tasks section in the Kubernetes documentation. Such solution-oriented documentation tends to attract links from developer sites. To the extent possible, to support this, we will develop and maintain a "blogs wanted" list of solutions for which we'd like a blog post. Documentation Content

Add a review checklist of documentation pages to be reviewed with each version release. This helps prevent staleness and inaccuracy. Or, if we don't have time to review them, at least we have a TODO list for contributors.

Build out the contributor section, encompassing the information in Contributing.md, and add information specifically about contributing to the documentation. Create and build out a Solutions section per the above.

Documentation Contributors

Launch a long-term campaign to attract documentation-only contributors in order to reduce burden on the primary maintainers. Such a campaign would include:

jberkus commented 4 years ago

Comments? Corrections? If this is a good plan, can the project owners approve it?

philips commented 4 years ago

Did you send this to etcd-dev? Very few people subscribe to notifications on this repo IIRC. You can cc etcd-maintainers@googlegroups.com. too.

spzala commented 4 years ago

adding @lucperkins

spzala commented 4 years ago

Thanks @jberkus Improving doc as you detailed sounds great to me! Wondering about couple of things

jberkus commented 4 years ago

A) No, it's based on feedback from a docs specialist and an SEO specialist B) There purposefully is not. That's one of the areas where the CNCF is very specific that they do not control or set requirements.

spzala commented 4 years ago

Thanks!

spzala commented 4 years ago

https://github.com/etcd-io/etcd/issues/12180 - doc improvement consideration related

nate-double-u commented 4 years ago

Hi 👋, I'm a Developer Advocate for documentation over at the CNCF, and I'd like to help with this project.

spzala commented 4 years ago

@nate-double-u thank you, that would be great! Would you like to compile the kind of improvements that you think of? I can schedule a meeting in the first week of December with maintainers. This week is KubeCon. We have a monthly meeting next week but it's a KubeCon week. Please feel free to ask any questions meanwhile. Thanks! /cc @xiang90 @gyuho @jpbetz @jingyih

jberkus commented 4 years ago

Meeting at the first community meeting in December would be awesome.

nate-double-u commented 4 years ago

I agree, the first community meeting in December would work for me as well.

spzala commented 4 years ago

@jberkus @nate-double-u - sounds great! Thanks!

wenjiaswe commented 4 years ago

Thanks, @nate-double-u @jberkus @spzala , I will add that to community meeting agenda.

spzala commented 4 years ago

Awesome, thank you @wenjiaswe !!

nate-double-u commented 3 years ago

During the planning discussions for this improvement work, the idea of migrating the documentation from the main code repo to the website repo came up.

I think that if we want to do this, we should do it as a part of this project.

I also think we should do this. There are some pros and cons, but I think that the positives outweigh the negatives.

Migration pros

Migration cons

Example sites

To see how this could look, here are some CNCF graduated projects that have their docs living in a separate website repo:

Each project in the CNCF does things differently though, so there are examples of projects keeping their docs in their code repos too.

nate-double-u commented 3 years ago

As a part of this Etcd.io Docs/SEO Improvement Plan, I'd like to suggest that we migrate the site to use the Hugo docsy theme.

Currently, anything that is not from the code repo's Documentation folder, or in the blog, is hardcoded into the layout html files, or has copy embedded in the config.toml file.

I think that reorganizing the site layout templates using the Hugo Docsy theme will make it easier to evolve and maintain the site and achieve the asks outlined

Outcomes

Process/Possible prep work

If we agree that this is a viable path forward, I'd like to do the docsy migration before building the rest of pages that @jberkus has outlined in the Documentation Content section above.

  1. Open an umbrella docsy migration issue
  2. Create a docsy branch
  3. Add docsy submodule to main
  4. (Consider) moving current site pages to content/en
  5. ... others as we move the process forward
ptabor commented 3 years ago

Some docs are generated, e.g. from protos: https://github.com/etcd-io/etcd/blob/69e99e80fa02a9120710039222ef085c6c36ea27/scripts/genproto.sh#L98,

so part of this script probably would need to be hosted in the 'docs' repo and pull source files from it.

nate-double-u commented 3 years ago

Some docs are generated

Good to know, thanks @ptabor!

nate-double-u commented 3 years ago

Based on a conversation with @chalin (who worked on the gRPC Docsy Conversion), I think the way I'd like to plan the next phases of work on this improvement plan are as follows:

  1. Migrate/consolidate the existing documentation into the etcd-io/website repo. (https://github.com/etcd-io/website/issues/93) 1.a. Clean up the existing site architecture. (Bring prose out of config files, layout file, etc. and make the site generally more hugo-like)
  2. Design new information architecture. Based on the "Documentation Content" section of the plan laid out by @jberkus above. This is where we'd decide which new pages need to be built, and what content they would have.
  3. Plan the Docsy migration.
  4. Migrate to Docsy (https://github.com/etcd-io/website/issues/94)
  5. Build new pages based on the architecture designed in step 2.

I'm not yet sure of the order of steps 4 and 5, I think there may be some advantage to doing them together. Things may become more clear as we do the planning. The cleanup phase may also help us understand better how the Docsy migration could go.

/cc @zacharysarah

nate-double-u commented 3 years ago

I've put together a spreadsheet for tracking tasks and estimating time.

https://docs.google.com/spreadsheets/d/1-ZQMPc_eQ0fh1pwOHv3NltwT-ifKA5UcFePfdFiWn8I/edit?usp=sharing

I'm hoping each line item can be made into an issue here on GitHub. It's not entirely complete yet, but as we move through the process we can add to and change it. I'm always happy for suggestions and feedback!

nate-double-u commented 3 years ago

I'm happy to say that PR https://github.com/etcd-io/website/pull/244 has been merged in, and we're now running the Docsy theme on etcd.io

The improvement plan continues! 🙂

chalin commented 3 years ago

make etcd.io the primary destination for information about how to run, deploy, maintain, and scale etcd, both as a real resource and via search engines.

What should be done (if anything) with https://github.com/etcd-io/etcdlabs, which is live at http://play.etcd.io/home?

nate-double-u commented 3 years ago

As @chalin and I will be migrating off the etcd.io project, I want to put together an update as to where the project stands and what still needs to be done. I’ll quote @jberkus’ original text as needed, but will prune duplications or parts that are answered in other sections. As there is quite a bit here, I’ll break this into several posts.

Milestone trackers

Tracking Issues

nate-double-u commented 3 years ago

Objectives

To make etcd.io the primary destination for information about how to run, deploy, maintain, and scale etcd, both as a real resource and via search engines.

What's Not Working

Currently etcd.io is often not the first hit when searching on common etcd tasks, such as "etcd setup", "how can I scale etcd", or "etcd troubleshooting". Instead, various random other pages are, some associated with our project (such as the CNCF blog) and some not (Rancher.com or Portworx pages). Importantly, because the most findable sources are not part of the official etcd documentation, the information on them is often out of date.

nate-double-u commented 3 years ago

Improvement Plan Short Term Home Page Improvements

Add the following static pages to the website, linked off a section on the home page:

* Documentation TOC - page with an annotated TOC for the documentation and direct links to important pages.
* Download Etcd - page with links to sources, packages, and containers for getting Etcd and installing it (cross-link to 3,4)
* Getting Started with Etcdctl - page with simple instructions on how to install and get started with Etcdctl, including authentication to existing clusters.
* Getting Started with Etcd - page with simple, 80% solution, instructions on installing Etcd on a Linux server.
* Troubleshooting Etcd - page with lots of links to things like how to analyze errors, how to file a bug, etc.  Add links to relevant blog posts as they get written.

Each of these static pages will live in the website repo rather than docs; as much as possible they will be somewhat version-agnostic. All basics will be covered on the static page, with links off of them only for more in-depth review or unusual circumstances (e.g. "etcdctl kerberos authentication").

nate-double-u commented 3 years ago

Documentation Content

Replace TOC for documentation navigation with one that makes more logical sense from a "user journey" point of view. This will be the same TOC displayed on the static page. At a top level, this would mean replacing the existing sections with the following:

There hasn’t been a new table of content page made, but the existing one, for each version since v3.4 has been reordered based on discussion about what best the info should be presented in (see Documentation Content: TOC — Compilation PR (weights & descriptions) https://github.com/etcd-io/etcd/pull/12575, and Adding weights and descriptions to v3.4 from next #168)

* Getting Started (some of which links back to static pages, or copies of those pages)
* Administration (Operations Guide + Upgrading + Platforms + some other pages which are operational, like Metrics)
* Developer Guide (Developer guide + Learning Etcd)
* Contributor Guide (Currently would include Reporting Bugs and Issue Triage, but more content later)
* Additional Information (FAQ + Benchmarking + some other pages)

Each section will be reworked so that it follows some kind of logical order, for example from installation, to growing the cluster, to upgrading. Note that this may require adding additional required header information into existing documentation files.

We also need to fix multi-version navigation. That is, switching "versions" of the documentation should automatically navigate to that page in the selected version of the docs, if that page exists. If this is challenging to do with the documentation toolchain we have, re-evaluate whether we want to keep versioned documentation.

nate-double-u commented 3 years ago

Blog

Encourage weekly blog posts of unique content, mostly alternating how-to articles and release updates (patches, etc.). The new content here will drive some traffic as well as supply material for future documentation.

Cleanup

Fix 404s: we have a lot of lost pages. These need to get replaced with redirects.

Shorten redirect chains (not sure how many of these we have)

Add a Documentation tag to both the Etcd and Website repos so that we can start tracking docs issues.

I had added a 'documentation' tag to the website repo, but have since removed it. There were very few instances of it being used, and by default issues being opened on the website repo are relating to documentation so it was a bit redundant.

Ongoing/Long Term

Blog Transfer

As we accumulate extra "How To" information into our blog, this content will be reworked in order to create a "Solutions" section for the documentation. This will be like the Tasks section in the Kubernetes documentation. Such solution-oriented documentation tends to attract links from developer sites. To the extent possible, to support this, we will develop and maintain a "blogs wanted" list of solutions for which we'd like a blog post.

Blog work noted in the process of reorganizing the site:

nate-double-u commented 3 years ago

Suggested Additions to the Improvement Plan

During the planning discussions for this improvement work, the idea of migrating the documentation from the main code repo to the website repo came up.

As a part of this Etcd.io Docs/SEO Improvement Plan, I'd like to suggest that we migrate the site to use the Hugo docsy theme.

jberkus commented 3 years ago

Thank you for your terrific work on this. The reorganization you've done will make it possible for us to maintain the docs better and in a more searchable format.

philips commented 3 years ago

Yea, thank you. The site looks great.

On Jun 28, 2021, at 4:18 PM, Josh Berkus @.***> wrote:

 Thank you for your terrific work on this. The reorganization you've done will make it possible for us to maintain the docs better and in a more searchable format.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

CIPHERTron commented 3 years ago

Heyy @nate-double-u @jberkus I would like to work on this issue. Could you please guide me on how to approach it? Thanks 🚀

wisdomekpotu commented 3 years ago

Hi @nate-double-u @jberkus , My name is Wisdom Ekpotu, I am a Third Year Computer Engineering Student from University of Uyo, Nigeria. I saw this project in the LFX mentorship fall 2021 and I thought this project had some parallels with my skills. I would love to contribute to this project and I'm open to learning any new technologies required for the project. Also does this project have an official Slack channel that we can join to get more information about the project.I am really looking forward to contributing to this project!

unnati914 commented 3 years ago

hey @wisdomekpotu ! The slack channel for etcd channel is in kubernetes workspace you could search it by name etcd in channel section Thank you!

unnati914 commented 3 years ago

Also, I went through the issue. Could I open a PR stating all the possible solutions? @nate-double-u , @jberkus ?

nate-double-u commented 3 years ago

For everyone who's joined us recently for the etcd Docs project with the LFX Mentorship Program, welcome, and thanks for your interest!

The CNCF has just published blog post with more information about all the projects, as well as timelines and links on how to apply: https://www.cncf.io/blog/2021/08/16/cncf-lfx-projects-are-open-for-fall-2021-apply-by-august-22nd/

rachittshah commented 3 years ago

Hello @nate-double-u @jberkus,

I've worked on a similiar project for my Google Season of Docs with HPX, a core C++ library of the STE||AR group, the project can be found here:

Made a local clone of the website and had couple of ideas as well.

I believe there's a couple of ideas -

I have submitted my cover letter and resume on the LFX portal, however I would like to start working on improvements right away, as it's open-sourced I would like to lend a hand irrespective of the program.

I would update on my progress here and by opening issues, are you open to testing new platforms?

@jberkus, a small request, can we setup a project board in the website repo? That would help us track objectives and key-deliverables much better.

Also @unnati914 @wisdomekpotu @CIPHERTron , let me know if you folks need help, I love to lend a hand.

unnati914 commented 3 years ago

hey @rachittshah :) Glad to see you here :) And yes I will surely approach you if I get stuck anywhere Thank you!

rgrupesh commented 3 years ago

Hello @nate-double-u @jberkus,

I went through the issue and I feel like I can accomplish this task. I am working on my cover letter, will submit that along with my resume through LFX portal.

Is there else that I should know of?

unnati914 commented 3 years ago

Hey @rgrupesh, for the application i guess you need two things only that is a resume and cover letter, to be submitted on LFX site

unnati914 commented 3 years ago

Also, you can join Kubernetes slack workspace, in case you need some guidance from mentors :) I hope it helps! The channel name is etcd

rgrupesh commented 3 years ago

Also, you can join Kubernetes slack workspace, in case you need some guidance from mentors :) I hope it helps! The channel name is etcd

This was helpful. Thanks again @unnati914 !

CIPHERTron commented 3 years ago

Hello @nate-double-u @jberkus,

I've worked on a similiar project for my Google Season of Docs with HPX, a core C++ library of the STE||AR group, the project can be found here:

Made a local clone of the website and had couple of ideas as well.

I believe there's a couple of ideas -

I have submitted my cover letter and resume on the LFX portal, however I would like to start working on improvements right away, as it's open-sourced I would like to lend a hand irrespective of the program.

I would update on my progress here and by opening issues, are you open to testing new platforms?

@jberkus, a small request, can we setup a project board in the website repo? That would help us track objectives and key-deliverables much better.

Also @unnati914 @wisdomekpotu @CIPHERTron , let me know if you folks need help, I love to lend a hand.

Heyy @rachittshah it's great to have you here. 🚀 Would love to work with you!

nate-double-u commented 3 years ago

I've worked on a similiar project for my Google Season of Docs with HPX, a core C++ library of the STE||AR group, the project can be found here:

⋮

Hi @rachittshah, thanks for your interest. It looks like you posted this message over in the slack channel as well. We probably don't need to post in multiple places, as then any response will need to be repeated across channels.

I believe there's a couple of ideas -

* How would you like to work with https://docusaurus.io/ ? It supports SEO+search much more in-depth, and looks modern too.

I appreciate your enthusiasm, but as I mentioned over in slack, we've just gone through a major overhaul on the etcd.io site. For this LFX docs mentorship project we'll be focusing on the technical documentation that needs to be completed. There may be some website work to be done, but primarily the work will be technical writing.

I have submitted my cover letter and resume on the LFX portal, however I would like to start working on improvements right away, as it's open-sourced I would like to lend a hand irrespective of the program.

I'm glad you've applied. I'd like to suggest that we wait before starting any work on the project as there is a process we're going through.

rachittshah commented 3 years ago

Thank you for the reply @nate-double-u , apologies for taking up too much space on the communication channels. Will keep in mind.

Sure, however I would love to try and contribute in the meantime, even if it could help the other contributors it would be great!

Thank you for your support, I would await your response prior to contributing to avoid breaking procedure.

Do let me know if you need help!

nate-double-u commented 3 years ago

Sure, however I would love to try and contribute in the meantime, even if it could help the other contributors it would be great!

There are some issues labelled "good first issue" (though there should be more than there are, I'll look into seeing if there are any more issues we can label as such), which may be a good place to start if you'd like to contribute before the end of the LFX docs mentorship project application phase.

wisdomekpotu commented 3 years ago

@nate-double-u, I just submitted my CV and cover letter on the LFX Portal to become a mentee on this project.

I have forked this repo began my research on the code base and will start contributing immediately.

nate-double-u commented 3 years ago

For everyone who has applied to the LFX docs mentorship program, thank you so much for your interest and enthusiasm. The candidate selection has been made and emails should have been sent out with the results. If you weren't selected, please don't get discouraged. There were a lot of strong candidates who applied, and I wish we were able to choose more than one. I encourage you to try again next term.