docs: README.md update - Consistency updates #2473
Conversation
VaclavElias
requested review from
tebjan,
Eideren,
manio143,
xen2,
Kryptos-FR and
Aggror
|
I still need to do a few tests but we can start the conversation. The main highlight is to bring clarity and direct game devs vs contributors where they should go. It might look reperative but it depends, where you land. So any of the pages mentioned below will direct/redirect you further. 
Get started with StrideThe Get started pages also adds some intro https://stride-doc-staging.azurewebsites.net/latest/en/manual/get-started/index.html
Install StrideAnd so do Install page https://stride-doc-staging.azurewebsites.net/latest/en/manual/get-started/install-stride.html
|
|
Additionally, this PR brings README.md consistency across: |
|
I think we can do without the table of contents, our readme isn't that long |
|
Re: Code of conduct, it has now a dedicated place. I learned about this one from other repos 😯 
|
|
The purpose of Table of Contents is really just a shortcut link to take you down, so you don't have to scroll. The title itself could be removed. You can check how it works here: https://github.com/VaclavElias/stride/tree/readme-update Earn Money, is a shortuct, which takes you down in the page, where is the old content. |
| 3. **[Visual Studio 2022](https://visualstudio.microsoft.com/downloads/)** (the Community edition is free) with the following workloads: | ||
| - **.NET desktop development** with **.NET Framework 4.7.2 targeting pack** (should be enabled by default) | ||
| - **Desktop development with C++** with: | ||
| - **Windows 11 SDK (10.0.22621.0)** or a later version (should be enabled by default) |
There was a problem hiding this comment.
Win 11 SDK ? Are you sure about this?
There was a problem hiding this comment.
100%, tested on clean Win 11. It is selected by default actually by the installer.
There was a problem hiding this comment.
We had there before Windows 10 SDK
There was a problem hiding this comment.
I think this requirement applies to UWP, so it's not a big deal. I wonder if version is also correct🤔
There was a problem hiding this comment.
It is, see below:
|
Overall I would keep README.md file as short as possible, so I would also concider removing TOC and shortify " Stride Documentation Landscape" paragraf maybe(?) |
|
Otherwise nice work |
| - Navigate to the `/build` directory in the command prompt. | ||
| - Run: | ||
| ```bash | ||
| msbuild /t:Restore Stride.sln |
There was a problem hiding this comment.
I guess both commands can be combined as well
| msbuild /t:Restore Stride.sln | |
| msbuild /t:Restore Stride.sln; compile.bat |
There was a problem hiding this comment.
I have to test this part also on clean Win 11. Once tested and working, I will take it 🙂
Have you tried this link? https://github.com/VaclavElias/stride/tree/readme-update The purpose of a Table of Contents is to help you quickly navigate to a section without scrolling. This becomes a time saver when you repeatedly access the same part of the page. If you only visit the README once a year, it might be unnecessary. But if you're there frequently, it definitely helps. If you and the team have considered this perspective and still see no benefit, then sure, it can be removed. 🙂 Regarding the Stride Documentation Landscape, there's also a strategic reason for its inclusion across all repositories: Docs, Website, and Toolkit. We face a challenge with users finding the material we already have. So, no matter which repository you land on, if you bother to scroll to the bottom, all the important links are available at a glance. This allows users to navigate anywhere without needing to go to Discord to ask where things are. This feature is a time saver for us, as we don't have to repeatedly direct people to certain parts of our documentation landscape. Ideally, users will find what they need themselves, allowing us to save our time for PRs and other tasks. 🤣 Also, it's intentionally placed at the bottom so it doesn’t clutter the top of the README. By the way, once the Docs Contributors https://doc.stride3d.net/latest/en/contributors/engine/index.html section is sorted and reviewed, we can move the entire Building from Source section to our docs. This way, we won’t have to maintain and update it in two places.
|
There was a problem hiding this comment.
It's cool to include more info. But adding more information is often counter productive, the more content you have the least likely users are to read things through.
Short and to the point is necessary, particularly for a readme.
we can move the entire Building from Source section to our docs
If we have to do this, I would rather we link from our docs to the readme instead. Users are cloning, opening issues and creating PRs from github, it makes more sense to have building instructions over here rather than 'hidden' in our docs.
Same idea, the more redirect there is, the more likely users are to just skip our instructions.
| ## Table of Contents | ||
|
|
||
| ## Earn money by contributing | ||
| If you are a developer with solid experience in C#, rendering techniques, or game development, we want to hire you! We have allocated funds from supporters on [OpenCollective](https://opencollective.com/stride3d) and can pay for work on certain projects. [More info about this here](https://doc.stride3d.net/latest/en/contributors/engine/bug-bounties.html). | ||
| * 🚀 [Getting Started](#-getting-started) | ||
| * 🤝 [Contributing](#-contributing) | ||
| - [Earn Money by Contributing](#earn-money-by-contributing) | ||
| * 🗺️ [Roadmap](#%EF%B8%8F-roadmap) | ||
| * 🛠️ [Building from Source](#%EF%B8%8F-building-from-source) | ||
| - [Prerequisites](#prerequisites) | ||
| - [Build Stride](#build-stride) | ||
| - [Build Stride without Visual Studio](#build-stride-without-visual-studio) | ||
| - [If Building Fails](#if-building-fails) | ||
| - [Contribution Guidelines](#contribution-guidelines) | ||
| * 🔬 [Build Status](#-build-status) | ||
| * 📖 [Stride Documentation Landscape](#-stride-documentation-landscape) | ||
| * 🌐 [.NET Foundation](#-net-foundation) | ||
| * 🛡️ [License](#%EF%B8%8Flicense) | ||
| * ✨ [Contributors](#-contributors) |
There was a problem hiding this comment.
Looks like github have added a TOC-like feature:
There was a problem hiding this comment.
They should name it as TOC or something so it is easier to discover 🤣. Anyway, that's awesome. I can remove my suggested TOC, including from other repos because it is now irrelevant. Thanks for suggesting this!
|
|
||
| ## Community | ||
| If you are a developer with solid experience in C#, rendering techniques, or game development, we want to hire you! We have allocated funds 💰 from supporters on [Open Collective](https://opencollective.com/stride3d) and can pay for work on certain projects. [More information is available here](https://doc.stride3d.net/latest/en/contributors/engine/bug-bounties.html). |
There was a problem hiding this comment.
Emojis are fine and all, but not in the middle of a sentence. It would be fine for a text message, not so much for a readme I don't think, it kind of feels like we aren't taking this seriously.
There was a problem hiding this comment.
Sure, it will be removed.
|
|
||
| The Stride documentation is organized across different locations. Here's how it's structured: | ||
|
|
||
| 1. [Stride Game Engine](https://github.com/stride3d/stride) - The main repository for Stride, a free and open-source 2D and 3D game engine. |
There was a problem hiding this comment.
The main repository for Stride, a free and open-source 2D and 3D game engine.
Maybe keep it as just
The main repository for Stride
It sounds like a marketing spiel/AI generated
There was a problem hiding this comment.
I think, I was trying to bring 2D word somehow somewhere because it isn't mentioned in the entire README 🤯 (so a new comer might wonder...) but it doesn't make sense to have it at the location you mentioned. I will make updates according your suggestions. We can word 2D in another PR.
| ### .NET Foundation | ||
| This project is supported by the [.NET Foundation](https://dotnetfoundation.org). | ||
| ## 🚀 Getting Started | ||
|
|
||
| ### License | ||
| Stride is covered by the [MIT License](LICENSE.md) unless stated otherwise (i.e. for some files that are copied from other projects). You can find the list of third-party projects [here](THIRD%20PARTY.md). Contributors need to sign the following [Contribution License Agreement](https://github.com/dotnet-foundation/.github/blob/main/CLA/dotnetfoundation.yml). | ||
| If you want to **create games using Stride**, please visit our [Get started with Stride](https://doc.stride3d.net/latest/en/manual/get-started/index.html) guide. This guide provides detailed instructions on how to download, install, and begin using Stride to develop your games. | ||
|
|
||
| If you are interested in **building the Stride engine from source** or **contributing to its development**, please continue reading this README for instructions on how to build from source and contribute to the project. | ||
|
|
||
| If you are interested in both, we recommend starting with the [Get started with Stride](https://doc.stride3d.net/latest/en/manual/get-started/index.html) guide, and then returning here to learn how to build from source and contribute. |
There was a problem hiding this comment.
This section is really long for how redundant it is, people will very likely just scan through the different headings we have to find what they are looking for instead of reading this.
There was a problem hiding this comment.
I think, this one is important for new comers. We can try to make it shorter and clearer. The aim is to figure out quickly the path one should take, as our current README is not clear and it was also confusing for myself.
I didn't know if I need to follow README if I want to make just a game, and if I need to build from the source to make a game. So there are at least 2 major audiences with different goals.
So the Getting Started section should help with what one want to achieve:
- Just creating games (not interested in Stride source code) - follow this path
- Building, debugging, improving and contributing the Stride source code - continue reading
I will try to redraft that section. Any suggestions anyone?
There was a problem hiding this comment.
That makes sense, perhaps building a short warning/info blurb mentioning that the content of the readme is specifically for users wanting to build or contribute to the engine itself, and redirect users that want to create games to the documentation instead.
I see, this is a good point. I will restructure the Docs and follow up with Aggor so it is easy to maintain which ever part should be here in README or in Docs. I believe, there will be more instructions in our docs later but we can always direct to README for the main instructions. The aim was to de-duplicate prerequisites and build instructions, so we don't have to maintain it in 2 locations. Let it be then README for these major instructions, so anyone cloning the repo would have the latest instructions. I will remove this https://doc.stride3d.net/latest/en/contributors/engine/building-source-windows.html#prerequisites and rather link to README. |
This pull request updates the
README.mdfile to improve its structure, readability, and navigation. The changes include adding hyperlinks, reorganizing sections, and enhancing the overall content to provide a better user experience.Enhancements to
README.md:Navigation and Structure:
Content Updates:
Hyperlinks and References:
Visual Enhancements:
These changes aim to make the
README.mdmore user-friendly and informative, helping new users get started quickly and existing users find the information they need more efficiently.# PR DetailsThis PR brings consistency across Stride repos.
You can see the updated version here: https://github.com/VaclavElias/stride/tree/readme-update
Related Issue
#2265
Types of changes
Checklist