Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New API docs - link colors and consistency #4

Open
Maksims opened this issue Jan 24, 2024 · 0 comments
Open

New API docs - link colors and consistency #4

Maksims opened this issue Jan 24, 2024 · 0 comments

Comments

@Maksims
Copy link
Collaborator

Maksims commented Jan 24, 2024

It would be great to have a very consistent color and style for links within docs. Color coding of different things - is great, but without consistency it is harder to get quickly familiar with things.

Code syntax highlight should match the color schema of the docs or vice-versa.

Use color only for meaningful color coding, and reserve a distinct color per type of element we want to highlight. E.g. Class should use the color that others don't use. And class should be everywhere highlighted with such color (lists, links, code examples, syntax highlight, etc).

Links

If anything is clickable, it should look as clickable, and other elements should not use same way of highlighting to avoid confusion.
Obvious navigation lists, e.g. list of properties, accessors, methods - do not require underlines.

Subtle underline can help with that:

Currently:
image

With underline:
image

Classes

For example, all classes are colored cyan:
image

But clickable links are all different colors:
image

Functions

Functions are purple:
image

But in docs it shows methods as Pink:
image

And then goes back to purple below for these methods:
image

But in syntax highlight we switch to yellow:
image

Properties and Accessors

In engine they are very close, in some rare cases it is worth to know distinction, but generally engine uses them interchangeably, without providing any meaningful difference to the user. End of the day accessors do behave like properties.
Biggest thing, is that list of properties and accessors - is a public API, and the splits into two separate blocks does not provide meaning, but makes it harder to overview.
Also they don't need to look different as they behave by the end user the same.
Obvious examples would be: Entity.path and Entity.name. But even everything else. It is confusing distinction in general for API overview:

image

@willeastcott willeastcott transferred this issue from playcanvas/developer.playcanvas.com Jan 24, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant