Page "Creating a Demo" - First time impressions #33
Description
During my first time using the SSS, I attempted to go through the "Creating a Demo" instructions from the documentation. My goal was to create a simple "Hello World" demo that displayed my desired text on the screen.
Here are some of the issues I encountered while going through this process:
Public-facing links to internal documentation
In the section screen (link), there is a brief paragraph describing a self.screen object, which "controls what will be drawn on the screen". It contains a link to an "API doc", which is a Notion page. This Notion page is not available to the public.
Suggestion: Fix this link. The page containing equivalent content to what is on our Notion page can be found in Tutorials > Game Display
Duplication of API content
The Notion page didn't have any specifics describing what the input parameters were for each function... which was not helpful for me, who wanted to actually use these functions instead of just get a high-level understanding of what they did.
I found equivalent Display documentation that did have all of the function explanations.
Suggestion: Merge these two sets of documentation into a single source that provides high-level explanations and the specific parameter details.
Inconsistent naming in the documentation
In the "Creating a demo" Tutorial mentioned earlier, the term used to describe the object that functions like draw_hline() and draw_text() can be called upon is screen.
But in this page, it is referred to as a Game Display.
And in the Display documentation, it is referred to as a Display.
As a new user, this added confusion and consumed time for me to figure out that all three terms referred to the same concept.
Suggestion: Adopt a consistent naming scheme across the entire documentation. Refer to this object as Display, since that is what the code uses.
Summary:
There is some inconsistency in naming scheme and duplication of documentation for a vital object. These issues can be resolved by merging all the documentation into a single location, using a single naming scheme.