📚 Elevating Stride's Documentation: Let's Discuss Our Strategy 🚀

[VaclavElias]

Documentation is the backbone of any project, particularly in the realm of software development and even more so for open-source initiatives. Quality documentation not only serves as a comprehensive guide but also draws in a larger audience and eases the onboarding process for new developers.

Current Documentation Landscape

Here's an overview of the current state of documentation within the Stride project:

Stride Website

• Purpose: A dedicated frontend website covering what Stride is about, as well as hosting our blog.
• Target Audience: General Public
• Current State: New design, old but updated content, more content needed
• Updates:
  • Current: Rare
  • Ideal: Frequent, with monthly blog posts
• Infrastructure: 11ty site generator, Azure App Service

Stride Website Wiki

• Purpose: Guidelines on how to update and build the Stride website.
• Target Audience: Contributors
• Current State: New
• Updates: Occasional, mostly related to site generator updates
• Infrastructure: GitHub Wiki

Stride Docs Website (referring to the new version which will be released soon)

• Purpose: A focused website on Stride's API, Manual, Tutorials, and Release Notes.
• Target Audience: General Public
• Current State: New design, old content needs review and improvement
• Updates:
  • Current: Once a year during version releases
  • Ideal: Frequent content updates and improvements
• Infrastructure: DocFX site generator, Azure App Service

Stride Docs Website Wiki (Upcoming)

• Purpose: Guidelines on how to update and build the Stride Docs website.
• Target Audience: Contributors
• Current State: New
• Updates: Occasional, mostly related to site generator updates
• Infrastructure: GitHub Wiki

Stride Engine Wiki

• Purpose: Low-level documentation on how to build the Stride engine.
• Target Audience: General Public, but mainly contributors
• Current State: Old, needs review and updating
• Updates:
  • Current: Rare
  • Ideal: As needed to keep docs up-to-date
• Infrastructure: GitHub Wiki

Action Items for Improvement

The infrastructure for our websites is updated; what needs focus now is the content.

Areas for Focus

1. Stride Website
   • Regularly review and update existing pages
   • Add new blog posts
2. Stride Docs
   • Review and update existing manuals
   • Add missing content
   • Increase the number of tutorials
3. Stride Code XML Comments
   • Existing and new C# code should have XML comments. This is crucial as these comments are ingested into the Stride Docs - API
4. Stride Engine Wiki
   • Update content to be consistent with Stride Web Wiki and Stride Docs Wiki

Note: For adding XML comments in Visual Studio, you can use the triple-slash /// shorthand to automatically generate some of the XML content.

For Reference

To understand the importance of XML comments and how they integrate into the documentation, you can visit DocFX Basic Concepts.

Let's work together to elevate Stride's documentation to the next level. We'd love to hear your thoughts:

• What specific improvements do you think our existing website/docs need?
• Are there any particular guides or documentation that you find lacking or missing altogether?
• Which sections do you believe require more focused attention?

Your ideas and input are invaluable to us, so please feel free to share.

Thank you.

[IXLLEGACYIXL]

For example take unity it has now this Documentation
https://docs.unity3d.com/ScriptReference/Rigidbody.html
which is just auto generated like docfx makes it ( and they have some weird manuals that nobody understands )

Unity had before for each "more" important an example of the usage which was loved by the community but they dropped that and swapped to the auto generated version.
So it would be good to have a somewhat option to be able to append to a auto generated page an example of how to use that thing
Which would also help AI answers to be more accurate as it has more to learn about
And AI becomes a more important part each day

[IXLLEGACYIXL]

We can't control where the Examples are shown in the generated docs

i meant that the order in the generated docs puts the examples at the top

[VaclavElias]

I am not aware that you can do that in DocFX, without some template fiddling. DocFX has this order: summary, param, returns, remarks, examples.

Also, my example is an example for the SetRange() method example. If you add any examples to the SoundInstance class itself, they would be at the top, if that is what you meant? See the example below

[manio143]

A note to be made is that docFX follows the way official Microsoft API docs are done - for many .net APIs the Remarks and Example sections are very large to provide the necessary context on how to use the class - e.g. https://learn.microsoft.com/en-us/dotnet/api/system.io.filestream?view=net-7.0
However, it doesn't seem to be sourced from the XML comment on that class https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/System/IO/FileStream.cs
It's defined in another repo
https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.IO/FileStream.xml

[VaclavElias]

Interesting and convenient. I will try to find out if it is possible with the open source DocFX we are using. Microsoft had branch 3.0, which they had to to make private, because it was becoming different from 2.70.3.

Anyway, if we could do that, it would be nice.

dotnet/docfx#8277 (comment)

[VaclavElias]

Found some input, I have to test it dotnet/docfx#8721

[manio143]

I think gathering frequently asked questions on discord and github would be a good driver for new content as well as getting around to documenting tutorials for some of the "basic" but not known things like working with how the content system and abstract file system layers work in Stride.

For each topic we want covered we should create an issue in the stride-docs repo so that a backlog can be formed and give contributors idea what to do if they don't have one of their own.

[VaclavElias]

Research done, the instructions will be in our wiki, or let me know if you would like to use it now :) Long remarks and examples can be in an external file.

[BldgBlocks]

Can I get a link to the instructions for this? I am not seeing them. I got into the wiki and then the Docs instructions but that's a separate system from the API docs generated from the code. The external file with much more info seems really interesting. I am looking to learn this process and then target an area with a pull request for documenting system or class areas.

[VaclavElias]

That is great, that you would like to help on this subject. The Stride wiki will be re-done, once we publish the new docs https://stride-doc-staging.azurewebsites.net/latest/en/. So the instructions aren't there yet.

I am testing this functionality here https://www.vaclavelias.com/stride-community-toolkit/ for example, this page has examples section https://www.vaclavelias.com/stride-community-toolkit/api/Stride.CommunityToolkit.Rendering.Compositing.GraphicsCompositorExtensions.html which are located here https://github.com/VaclavElias/stride-community-toolkit/tree/main/docs/examples.

That means, that most likely we are going to have the same process for Stride Docs website. I have created already a new folder in the new Stride Docs https://github.com/stride3d/stride-docs/tree/staging/en/examples, which can host these examples.

There are already 2 templates. The examples and remarks need to be in separated files. The syntax is markup + extra markup goodies from docfx https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet which could have also diagrams 🤯

The important part it, how to link these files with the Stride API, that is done through uid.

---
uid: Stride.Utilities.Test
remarks: *content
---

In some cases, it is easy to get uid (it is just a pattern) from the namespace, in some cases, it might be a long string. Not sure what is the best way to get uid, I get it by right click on the name and then I can see date-uid attribute with the uid value.

I would suggest to explore this functionality, make a plan, and once the New Docs is in the master branch, then you could start doing PRs :) I hope it will be there in a few days.

If you would like to test it locally, you would need to make New Docs (staging branch https://github.com/stride3d/stride-docs) running on your local PC.

But I could test it for you as well, if you add any content to the /examples folder.

Furthermore on this subject, generally we need better XML comments through the code base, which can be done directly in the Stride Engine code base.

Thank you for any assistance :)

[BldgBlocks]

Thank you for your great response! I will explore those resources. Diagrams is something I have been looking for! I use Diagrams.net, formerly draw.io, which is free as well. Mermaid is cool, as I saw, but much more limited in adjustability.

Diagrams.net has integration with GitHub, it has an embed mode, you can have the base file, export to other file types. You can even put the whole diagram in a URL and send or embed it.

Let me know your thoughts on if you think Diagrams.net would be an acceptable option. Here is a link that describes GitHub usage where you can embed and even edit within GitHub through 'embed mode'.
https://www.drawio.com/blog/embed-diagrams-github-markdown

[VaclavElias]

You're welcome! Regarding our wikis, they are hosted on GitHub Wikis, so we can utilize any diagramming tool that is compatible with that platform 🙂.

For our websites, the situation is a bit different:

Stride Docs: This site is built using DocFX, which natively supports Mermaid for diagramming. However, you are also welcome to add images or embed other types of content if needed.

Stride Web: This site uses 11ty, and we have the flexibility to add any plug-ins as required.

While we don't impose restrictions on the types of diagrams used, we are cautious about adding more components to the docs. Maintenance can be time-consuming, and sometimes even the diagrams themselves require updates. Therefore, unless they are quite generic, we try to be selective.

[Aggror]

Great work @VaclavElias.
Taking initiative on topics like this is key in its success. Provide a good starting point were people can add examples and more will join.
Let me know, if I can help out with providing some content.

[VaclavElias]

Thank you! It's evident that maintaining up-to-date and comprehensive content across all our websites is no small feat 😅. Everyone desires top-notch documentation, but very few are willing to contribute to it 🤣.

The initial discussion above has already helped us identify a key focus—figuring out how to offload examples and remarks to separate files.

To tackle this comprehensively, we could divide our efforts 50:50 on the following tasks, once the new Docs is live:

1. Reviewing and Updating Manuals: This involves revising existing manual pages and adding new ones 📝.
2. XML Comments and Annotations: This will include identifying and updating existing XML comments, as well as adding new remarks and examples 📚.

[BldgBlocks]

1. The Stride Docs has its own repo with its own PR system. The Docs main page has a writing guidelines link. That link currently does not work. But if you go to the wiki and find the Content.md it does have guidelines for the broad scope of work you will do.

2. The Docs page 'Tips' you that this is Docs only and for API you should go to 'Stride Contributions Instructions'. This takes you to the main Stride repo page. Which has lot of different info; license, docs, building, community.

   • If you follow the main page through the community section there are some discussions on API docs contributing but nothing really helpful for a structure or how to contribute comments effectively.
   • If you follow the main page down through to near the bottom there is a Contributing Guidelines link. This is generic for all types of contributions and contains very limited information. Request approval, make changes, submit changes, and see if they are accepted.
     • The .editorconfig is automatic for using the solution and is great for code style and contributions.
     • Related to this, there is a link in the Docs section that is applicable for how to understand how xml comments interact with DocFX. That would be useful here.

3. API documentation needs its own contributors guidelines section.

   • Public user facing comments.
     • I know @VaclavElias is compiling instructions on using separate files for examples and the uid system.
     • Structure should probably mirror a lot of what is already listed for the Docs contributing guidelines, especially since it is noted that these comments can be ingested into the Docs.
   • Contributor/maintainer facing comments.
     • I don't know how this should be handled without becoming junk. But as people come and go some of that existing reasoning, TODO's, future refactoring plans or known limitations from the last work, that stuff should be documented and maybe a structure could be suggested. Although I think any running lists should be avoided at all costs. Maybe a contributors page in the API manual for technical understanding would be best?

4. To sum up a bit. The linking for contributing should be clear and direct and have page of expectations. One route is contributing code. One route is contributing API comments. These are a compliment of user Docs (which has its own system). Currently it seems like it's just "go out and make comments" and I hope we can structure this a bit and hopefully speed up the PR submittal and review process.

[VaclavElias]

Thank you for summarising and providing your suggestions. I will be evaluating/processing all your points, which should help me to get the docs improved.

Regarding the Stride Contributions Instructions, I called it as a Stride Engine Wiki at the top, needs to be re-done and updated correctly.

Once I stabilise the new docs, which we just released, I would like to start with the contributors instructions/guides.. I will be in touch with everyone 🙂

[Fydar]

I created a tool for my own consumption called Fydar.Samples to generate and manage code samples.

After talking to technical writers at Unity, I found they have a very similar tool that allows them to do similar things with their code samples.

• Proper syntax highlighting
• Clickable links to other pages both within the documentation and to Microsoft's own documentation
• Rendering to SVG so I can have pretty code samples in .README files
• Uses Roslyn behind the scenes to achieve high accuracy

I made documentation using my own template similar to DocFX.
https://fydar.github.io/AssetIcons/Documentation.html#creating-extensions

If there is interest in this, I might focus on making a DocFX plugin that can give Stride better code samples ✨

[VaclavElias]

That sounds rather like an official plugin for DocFX, so anyone outside of Stride could use it? 🙂 Also, you don't have there yet a copy snippet icon!

[VaclavElias]

If anyone would like to see it in action, check the dotted links in the mentioned example https://fydar.github.io/AssetIcons/Documentation.html#creating-extensions