Etcd.io Docs/SEO Improvement Plan #65
Comments
|
Comments? Corrections? If this is a good plan, can the project owners approve it? |
|
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. |
|
adding @lucperkins |
|
Thanks @jberkus Improving doc as you detailed sounds great to me! Wondering about couple of things
|
|
A) No, it's based on feedback from a docs specialist and an SEO specialist |
|
Thanks! |
|
etcd-io/etcd#12180 - doc improvement consideration related |
|
Hi 👋, I'm a Developer Advocate for documentation over at the CNCF, and I'd like to help with this project. |
|
@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 |
|
Meeting at the first community meeting in December would be awesome. |
|
I agree, the first community meeting in December would work for me as well. |
|
@jberkus @nate-double-u - sounds great! Thanks! |
|
Thanks, @nate-double-u @jberkus @spzala , I will add that to community meeting agenda. |
|
Awesome, thank you @wenjiaswe !! |
|
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 sitesTo 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. |
|
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 workIf 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.
|
|
Some docs are generated, e.g. from protos: so part of this script probably would need to be hosted in the 'docs' repo and pull source files from it. |
Good to know, thanks @ptabor! |
|
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:
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 |
|
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! |
|
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 trackersTracking Issues |
|
|
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) etcd-io/etcd#12575, and Adding weights and descriptions to v3.4 from next #168)
|
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.
Blog work noted in the process of reorganizing the site:
|
Suggested Additions to the Improvement Plan
|
|
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. |
|
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.
|
|
Heyy @nate-double-u @jberkus I would like to work on this issue. Could you please guide me on how to approach it? Thanks 🚀 |
|
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. |
|
hey @wisdomekpotu ! The slack channel for etcd channel is in kubernetes workspace you could search it by name etcd in channel section |
|
Also, I went through the issue. Could I open a PR stating all the possible solutions? @nate-double-u , @jberkus ? |
|
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/ |
|
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. |
|
hey @rachittshah :) Glad to see you here :) And yes I will surely approach you if I get stuck anywhere |
|
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? |
|
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 |
|
Also, you can join Kubernetes slack workspace, in case you need some guidance from mentors :) |
This was helpful. Thanks again @unnati914 ! |
Heyy @rachittshah it's great to have you 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 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'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. |
|
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! |
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. |
|
@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. |
|
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. |
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:
The text was updated successfully, but these errors were encountered: