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.
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. |
|
I have made updates based on the feedback. Note that we are being a bit contradictive with our intetion to keep README short and clear, but we are adding here Build instructions which can't be actually short as anything missing will drive questions to Discord where we are going to repeat ourselves. We can obviously highlight a link to our Stride Contributors Docs, where we can write more detailed instructions on the go, once this is done in the docs. For now, the instructions remain the same, there are just a few more notes based on the Discord discussions (e.g. restarting computer after SDK installalion). Summary of this PR
|
|
You can see here the updated README https://github.com/VaclavElias/stride/tree/readme-update This PR can be further reviewed or merged. |
|
Looks good, on my end the logo is broken, but that might just be me ? |
|
Can confirm the logo loaded for me but on the second time opening for some reason. |
|
The logo is now also a link 🙂. Maybe some kind of caching on your side. Regarding the roadmap, you are right. Updating the docs is a slow process because the build takes 20-40 minutes and then the cache update around 24 hours. Maybe, we can create a project called Roadmap Avalonia Editor Rewrite (view) and simply organise some PRs there in a way it suits. It will be easier to visualise. And then we can link from README to this project and also change the docs, keeping there only static content, and link to the GitHub project. What do you think? |
I'll probably forget to do this if I am honest |
|
It's fine to me, I'll merge this in, if someone is not too keen on some of the changes feel free to open a PR to improve further |
Don't worry, there are a few of us who could manage this 🙂 |
That's expected, README needs to be up to date, and we can come up with better wordings or updates. Anyway, thanks. |
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