You are viewing a plain text version of this content. The canonical link for it is here.

Posted to commits@airflow.apache.org by GitBox <gi...@apache.org> on 2021/06/14 09:47:31 UTC

[GitHub] [airflow] peter-gergely-horvath opened a new issue #16431: Documentation landing page links in the section headers are hard to find

peter-gergely-horvath opened a new issue #16431:
URL: https://github.com/apache/airflow/issues/16431

<!--

Welcome to Apache Airflow! For a smooth issue process, try to answer the following questions.
Don't worry if they're not all applicable; just try to include what you can :-)

If you need to include code snippets or logs, please put them in fenced code
blocks. If they're super-long, please use the details tag like
<details><summary>super-long log</summary> lots of stuff </details>

Please delete these comment blocks before submitting the issue.

-->

<!--

IMPORTANT!!!

PLEASE CHECK "SIMILAR TO X EXISTING ISSUES" OPTION IF VISIBLE
NEXT TO "SUBMIT NEW ISSUE" BUTTON!!!

PLEASE CHECK IF THIS ISSUE HAS BEEN REPORTED PREVIOUSLY USING SEARCH!!!

Please complete the next sections or the issue will be closed.
These questions are the first thing we need to know to understand the context.

-->

**Apache Airflow version**: N/A - current documentation

**Kubernetes version (if you are using kubernetes)** (use `kubectl version`): N/A

**Environment**: N/A

- **Cloud provider or hardware configuration**: N/A
- **OS** (e.g. from /etc/os-release): N/A
- **Kernel** (e.g. `uname -a`): N/A
- **Install tools**: N/A
- **Others**: N/A

**What happened**:
I had spent quite some time looking for the documentation pages on https://airflow.apache.org/docs/ till I realized that actually the section headers are the links to the documentation pages. This is highly counter-intuitive (a link on a section header is normally a _permalink to the section header_ and not another page.) and is generally a **terribly bad UI user experience**.
For the first glance it seems Airflow does not have any documentation apart from the landing page!

**What you expected to happen**:
Documentation pages should be intuitive to navigate. One would normally expect proper links to other sections of documentation. For example: "Read the Documentation >>" as link text at the end of each section or something similar.

![airflow_documentation_page](https://user-images.githubusercontent.com/15800802/121871981-0bb6ec00-cd05-11eb-96b0-d3ad12d4426b.png)

**How to reproduce it**:
Get someone new to the project look at the documentation landing page with a fresh pair of eyes and ask them to locate the links to the main documentation.
<!---

As minimally and precisely as possible. Keep in mind we do not have access to your cluster or dags.

If you are using kubernetes, please attempt to recreate the issue using minikube or kind.

## Install minikube/kind

- Minikube https://minikube.sigs.k8s.io/docs/start/
- Kind https://kind.sigs.k8s.io/docs/user/quick-start/

If this is a UI bug, please provide a screenshot of the bug or a link to a youtube video of the bug in action

You can include images using the .md style of
![alt text](http://url/to/img.png)

To record a screencast, mac users can use QuickTime and then create an unlisted youtube video with the resulting .mov file.

--->

**Anything else we need to know**:

<!--

How often does this problem occur? Once? Every time etc?

Any relevant logs to include? Put them here in side a detail tag:
<details><summary>x.log</summary> lots of stuff </details>

-->

--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org