Hi all,
@xen2 and I have been discussing on how to improve the API documentation for Xenko. Right now when you visit the generated API documentation, you get a massive list of classes, methods, members and many other objects. Currently it is bloated, cramped with information, lacks any good examples and is frightens new members.
We can have cool (video)tutorials and community projects all we want: it wont matter as much since the API documentation is so hard to get a decent look at. So before I make all kinds of game tutorials and “How to” tutorials (like unity does it), lets first try to improve the core API documentation.
Some ideas
- Custom TOC: The current main list of items in the API reference is far too bloated. We could reduce this to custom sections, with each section a handwritten summary that could then list what it contains. That means we don’t need to have ‘Xenko’ name in front of every category. Right now it only clutters things up.
For instance the UI code, This can be reduced to a single UI category and have the subclasses/pages be referenced from there on out:
- Wide theme: The current api documentation template uses only a fraction of the screen space available. We could extend this to make full use of a users browser width. In my example with a 2k monitor: Basically half the screen is white. This also gives some breathing space
Current:
Vs wide theme (2 lines of css):
-
Let Xenko reference a sample file: this sample file resides in a new solution which could be added to the Xenko source for versioning. This is an actual project were code can be attached to example scenes. That means the code is always checked against the latest version. Plus it gives users a far better idea on how to use the API commands.
- A single script can demonstrate multiple commands
- XenkoDocs can reference files in Xenko repo (Xen2 tested this)
- The code referenced from file, does not have to be the entire file, it can be a segment from that file (Xen2 tested this)
Lets have a look at a very common class Input
- The TOC for Input could have collapsed subsections for Classes/Enum/Interfaces/structs
- One member per page (instead of one class per page): Something that personally stands out for ne at Unity API documentation, is the number of available example scripts. With the Xenko API all members of the class are listed on the same page. Unity has a page per member approach, which gives more room for adding examples.
Try comparing these two:
https://docs.unity3d.com/ScriptReference/Input.GetKeyDown.html vs
https://doc.xenko.com/latest/en/api/Xenko.Input.InputManager.html#Xenko_Input_InputManager_IsKeyPressed_Xenko_Input_Keys_
I know writing these kind of example are a lot of work, but I am willing to put some serious time on this. We don’t have to cover everything and we don’t have to have everything ready at the same time. We could gradually add new examples.
What are your thoughts/ideas?
