search

kubernetes / website

Kubernetes website and documentation repo:
https://kubernetes.io
Creative Commons Attribution 4.0 International
4.5k stars 14.43k forks source link

Reorganize pages in Tasks section #22788

Closed sftim closed 3 years ago

sftim commented 4 years ago

This is a Feature Request

What would you like to be changed Update the tasks section to reorganize the existing pages within a better defined and more navigable layout, such as:

Why is this needed The existing Tasks pages have a number of issues, including

Comments Relevant to issue #22786

sftim commented 4 years ago

Here's a layout we could adopt:

sftim commented 4 years ago

/kind cleanup /language en

sftim commented 4 years ago

@tengqm, you had some reservations about making this change?

tengqm commented 4 years ago

@sftim No, I am not a big fan of this effort for several reasons. Most of the tasks are talking about different aspects of managing, accessing applications, or managing the cluster itself. I'm doubting there is any inherent logic between security and managing resource limit or quota. There are always a thousand ways to navigate the tasks or even the concepts, although we can somehow categorize things into different levels e.g. basics, intermediate or advanced etc.

Another factor we may want to consider is that our audiences are from different background. They may be using hosted clusters or just a single node setup... Not all of the tasks are useful for all users. That is something we cannot change no matter how we reorganize the tasks to make the topics flow. In other words, the topics will never flow, I'm afraid.

Yet another reason I'm against this is that we will be introducing a lot of chaos into the community. It is hard to track which paragraph/page was moved, when and where. If the reorg does improve user experience significantly, we can communicate that to the localization teams. However, if the reorg itself is something in question, something of limited value, we'd better think twice. It may seem not a big change when we restructure a paragraph. When you consider for a moment the big picture ... we have 15 localization teams today. That change must be propagated into 15 subdirectories eventually, after reworked by 15 other people who resynchronize the text line by line, and another 15 people to review it.

I do personally appreciate the intent and the effort to improve the docs in whatever way. What I'm trying to articulate is that we may be on the wrong track if we are going down this road.

If we are trying to make the site easier to navigate, we can still avoid doing it in a disruptive way like reorganizing the topics. We may instead want to design a navigating subsystem, in addition to the current directory structure and search engine. For example, if I'm an engineer trying to find documentations on improving the performance of the cluster, what kind of topic groups can we offer? If I'm instead a developer trying to diagnose some application availability issue, do we have a list of topics for him/her to read? If I'm a newbie in this cloud native space, where should I start: Managing Kubernetes objects or running applications or some tutorial about kubectl?

kbhawkey commented 4 years ago

Re: what kind of topic groups can we offer Is there any interest in adding metadata to the task files -- to possibly use this data for searching and dynamic grouping of tasks, presenting different task views. Not sure if that would be confusing.

sftim commented 4 years ago

adding metadata to the task files

That sounds like a great idea - maybe another issue inside the same umbrella issue?

tengqm commented 4 years ago

Indeed, tagging is a good idea. Not sure if hugo has some tag specific features to leverage.

sftim commented 4 years ago

Not sure if hugo has some tag specific features to leverage.

There are various options. One that I like the idea of is creating headless bundles that represent groups of tasks. Each bundle could be a Markdown list of links, and then we give Hugo and Sass the job of rendering those nicely.

That approach lets a task appear in more than one grouping.

kbhawkey commented 4 years ago

Headless "bundle" strikes again 👻 . Could work -- have not considered how or why.

When I originally mentioned looking into the tasks section, I was thinking more along the lines of revitalizing the section. I would consider renaming this umbrella issue. This could mean some reorganization, but that was not my main point. I like the idea of tagging or providing more hints about what readers can get out of a task (what is the goal of the task). However, some of the "revitalization" could be cleanup of the content and ensuring that the task content is relevant to the concept content. Adding metadata would be helpful and then "bundles of tasks" could be created or featured. I have not looked into/used Hugo taxonomies.

kbhawkey commented 4 years ago

While cleaning up content in PR #24772, I thought it may be interesting to add metadata in the task page front matter. The metadata could tag a task with a list of related APIs (add more data as needed). This may help categorize the tasks. Later on, the metadata could be used to connect up other pieces of content on the page or other places in the site.

fejta-bot commented 3 years ago

Issues go stale after 90d of inactivity. Mark the issue as fresh with /remove-lifecycle stale. Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle stale

fejta-bot commented 3 years ago

Stale issues rot after 30d of inactivity. Mark the issue as fresh with /remove-lifecycle rotten. Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community. /lifecycle rotten

fejta-bot commented 3 years ago

Rotten issues close after 30d of inactivity. Reopen the issue with /reopen. Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-contributor-experience at kubernetes/community. /close

k8s-ci-robot commented 3 years ago

@fejta-bot: Closing this issue.

In response to [this](https://github.com/kubernetes/website/issues/22788#issuecomment-808942926): >Rotten issues close after 30d of inactivity. >Reopen the issue with `/reopen`. >Mark the issue as fresh with `/remove-lifecycle rotten`. > >Send feedback to sig-contributor-experience at [kubernetes/community](https://github.com/kubernetes/community). >/close Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.