All of the information that was present on any given page of the wiki should still be present. If you look at any page on the old wiki and find something on that page, you should be able to find the same information on the respective page in the new wiki. It shouldn’t force you to navigate several different pages to find the same information you could find on one page before. It also shouldn’t force you to scroll page lengths to find the same information, either. I don’t want to have to hunt for what I’m looking for.
1 Like
Templated extensions of types from the wiki (such as Ref<Instance>, dictionary<string,array<int>>, etc) are not coming back right away. I do want to bring this data back, but I want it to be integrated in the JSON API Dump instead of being some hacky override field that we have to add in ourselves.
For descriptions, we could have only a couple of lines showing and then have something that says “Show More”, that way people that want to read the description further can, but it also doesn’t take up a massive amount of space.
Layout
Personally, I already know what a particular item does, but I will still visit its reference page often for a refresh on what the item’s signature looks like (namely, function parameters).
So, I prioritize information that I want to see first. I use this concept in my API reference, so that can be referred to for examples.
Content on a page is categorized in two ways:
- Short content: Information is brief, compressed, and easy to scan, so that the user can get to the information that they want quickly. Information must not be hidden and requiring expansion to view. Short content should contain links to a longer form of the content when possible. Short content should appear towards the start of the page.
- Long content: Information is verbose and thorough, providing a full description of what an item does and how it works, so that the user can learn about the item. Long content should appear towards the end of the page.
Class pages
As an example, here is my dream layout of a class page.
-
Title
- Name of the class.
- Metadata in Short form, utilizing icons and other visual markers (e.g. strikethrough for deprecation)
- Breadcrum trail indicating inherited classes.
-
Summary
- Short form description. Short enough to be embeddable in other pages that summarize classes.
- A link to the Long form description.
-
Table of contents
- Allows the user to navigate the entire page quickly. Should be an overview of the page itself, but also brief so that it may be scrolled past quickly to the next, arguably most relevant, section.
- Member summaries
- Detailed description of class
- Detailed description of members
- Relevant pages
- Allows the user to navigate the entire page quickly. Should be an overview of the page itself, but also brief so that it may be scrolled past quickly to the next, arguably most relevant, section.
-
Member summary
- Provides a list of members.
- Metadata is presented in Short form through icons (e.g. member type, security context) and visual cues (e.g. strikethrough for deprecation).
- Inherited members are displayed by indicating the amount of members, and the class they are inherited from (example). Each of these elements can be expanded to show the full list of members. They are hidden in this way because they aren’t as interesting for the current class. If hiding is undesirable, then they should at least be marked to indicate that they inherited, and sorted with a lower priority.
- Deprecated members should be sorted with low priority, since they aren’t as interesting.
- The list should be sortable by each column.
- No descriptions! Too verbose. Instead, each item in the list links to its full description, which is further down the page.
- Member lists could be separated by member type, or crammed together. I consider this a toss-up.
- Some classes have many members, where it is better to separate them. Other classes have few members, where keeping them together would be less cluttering.
- In theory, the member type would determine which columns are present, so it would be better to separate them. In practice, no member really has outlying information that would require unique columns.
- Icon: Every member has an icon.
- Type: Property type, function/callback return type. Events don’t have this, but maybe that’s okay.
- Name: Every member has a name. Parameters could be included here.
-
Detailed description
- A description of the class in Long form.
- Includes those colossal notes about being deprecated or a service or other such metadata.
-
Member descriptions
- Contains descriptions for each member.
- Includes all metadata in a more descriptive form.
- Starts with a Short form description, followed by the Long form. The Short form can be used for embedding elsewhere.
-
Relevant pages
- Links to tutorials and guides involving the class.
It might also be convenient to include a summary of enums used by the class. Though I haven’t figured out a good place to put it.
Side panels
On small screens, side panels would be removed entirely, so the information within them should be non-essential.
- Left: Class list
- Sortable by category, by inheritance, and alphabetically.
- As the screen gets smaller, this should be removed first.
- Right: Table of contents
- Brief: Only includes essential headers as described previously.
- Verbose: Also includes list of non-inherited members. Maybe subclasses as well.
On large screens, the ToC is placed in the right side panel in Verbose form. On small screens, the ToC is moved inline, after the class summary (as described previously), in Brief form.
Security contexts
Users will only want to see the information relevant to what they are doing. If they’re programming a client, then they only want to see items that can be used in LocalScripts. If they’re writing a plugin, then they want to see items that can be accessed by plugins. Or maybe they just want to see all available items.
The LOVE2D wiki has a setting (stored in local storage), in the upper-right corner that shows and hides API items based on which version they were added or removed. A similar concept could be used to show and hide members with security contexts. The user selects an identity, and only members that match that identity will be shown.
17 Likes
I’m sure someone already brought this up, but I found it odd that we can only change the theme of the code panels:
Can you please go the full step and make the entire page have a toggle for a light / dark theme?
4 Likes
And also make it save our choice please
1 Like
Personally, Yes. Those descriptions are only read when I dont understand what’s on the left, and that’s usually the reason I open the page, it’s really not much harder to read especially with the alternating grey-white backgrounds. 
Ideally what we want to do is strike a rational balance between being able to distinguish between what member description you are currently reading and being able to easily navigate to the member you want to get to using the table of contents widget on the right hand side.
The alternating grey-white backgrounds on the wiki are really hard to distinguish. We could make the grey a bit darker, but that would just look silly and I don’t think that’s what we want it to look like.
If you believe it is a significant burden on your experience, I would advise using a chrome extension that allows you to adjust the CSS to your needs.
4 Likes
The striping on the old wiki was a bit hard to see depending on your monitor settings, and I can’t see the single striped table the old wiki had fitting with the style of the new website.
I think keeping members separated into “cards” like they are on the new website is a good idea. The white space and padding just needs to be kept sane, and all is bueno.
It’s only a matter of time until somebody makes a CSS theme that makes the new website look exactly like the old wiki.
2 Likes
A few thoughts of mine. To start, I typically use the wiki to quickly reference specific syntax of an API (what inputs it needs and in what order) so what I like right now about the current wiki layout is the high-density list format that allows me to quickly find the specific API via type (property, function, event) and then alphabetically by the specific API name.
With that being said, I think I would prefer keeping the name, type, and description all in line with each other.
Referring to the layouts presented, I like in #2 in the “Inherited from” section how I can quickly see everything inherited from whatever. However, I somewhat dislike how some lines have multiple functions or events on a single line. It feels a bit unnatural to read/skim through. The other part I’d like to see in that section would be even just a super short description of what it does\
In regards to properties unique to a specific object/whatever I prefer #1 since the name and type are in-line with each other and it feels easier to skim down the list.
Not sure how I feel about the side bar on the right. The one in #1 gives me the feel it would take me to other pages. It’s design seems to give the feel of site navigation rather than page navigation. #2 feels more like page navigation though maybe slightly bloated because it’s listing literally every property, function, and event. Though I suppose that could also be a good thing and I’d probably pick #2 over #1 just because it feels more like page navigation rather than site navigation.
One last thing. PLEASE PLEASE PLEASE get rid of the double-spaced look. I go to the wiki for information and the double-spacing just makes it harder and longer for me to find the info I need.
3 Likes
This topic was automatically closed 120 days after the last reply. New replies are no longer allowed.