KhronosGroup / KhronosGroup/Vulkan-Tutorial

Improvements to the README.adoc

Open Beginner friendly
#497 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
418
Forks
126
Avg merge
11d 6h
Merged PRs (30d)
31

Description

## Summary

The root `README.adoc` can be confusing for new readers. It largely mirrors the `00_introduction.adoc` to the Khronos Vulkan Tutorial, but the repository now contains multiple tutorials, so this is less relevant and more confusing.

I have received feedback from beginners who were unsure what content the repository contains and where to begin.

## Proposed changes

### Fix links - BUG

On GitHub’s rendered README, the links are broken. I think most of them need to be changed like this, to add `en/`:

```diff
- * xref:ML_Inference/introduction.adoc[Machine learning inference]
+ * xref:en/ML_Inference/introduction.adoc[Machine learning inference]
```

Note: that the `README.adoc` is not part of the main Vulkan website.

### Reorder and expand the opening

Start with an **About** section rather than **Attribution**. Attribution is important and makes sense at the start of the primary tutorial’s introduction, but the repository `README.adoc` should first explain what the repository contains.

### Expand the About section

Expand the About section to state that the repository hosts multiple Vulkan tutorials, including the primary Khronos Vulkan Tutorial and more focused tutorials covering advanced features.

```AsciiDoc
This repository hosts the contents of the link:https://docs.vulkan.org/tutorial/latest[Khronos Vulkan Tutorial]. The tutorial is part of the link:https://github.com/KhronosGroup/Vulkan-Site[Vulkan Documentation Project].

The primary tutorial is the Khronos Vulkan Tutorial. It updates the traditional link:https://vulkan-tutorial.com/[Vulkan Tutorial by Alexander Overvoorde] to use modern Vulkan extensions and practices. See xref:en/attachments/00_Introduction.adoc for a quick start.

The repository also includes tutorials on advanced Vulkan topics. See the tutorial documentation for the full list xref:en/00_Introduction.adoc[here].
```

### Clearly scope tutorial-specific sections

The **Attribution**, **Differences**, and **Installation Dependencies** sections concern the primary Khronos Vulkan Tutorial. Make this clearer.

### Update Project Structure

Expand **Project Structure** to identify the locations of the additional tutorials.

### Clarify licensing

Expand **License** section to distinguish the licenses for different tutorial content:

- The primary Khronos Vulkan Tutorial and Arm tutorials are licensed under CC BY-SA 4.0.
- Holochip-authored tutorials are licensed under Apache-2.0.
- Code listings are licensed under CC0-1.0, where applicable.

Also maybe we could consider adding `SPDX-License-Identifier` comments to source, tutorial, and AsciiDoc files to make this clearer.

Contributor guide

Open the contributing guide

Research direction

Start with the root README.adoc and inspect the referenced en/ paths to verify the GitHub-rendered links. Reorganize the opening around an About section, clarify which sections apply to the primary tutorial, expand Project Structure, and document the stated content licenses. Done means the README accurately describes all tutorials and its links render correctly on GitHub.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.