KhronosGroup / KhronosGroup/Vulkan-Tutorial
Improvements to the README.adoc
- 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
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