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

Documentation Improvements #2895

Open
5 of 13 tasks
spydon opened this issue Dec 2, 2023 · 14 comments · Fixed by #3072
Open
5 of 13 tasks

Documentation Improvements #2895

spydon opened this issue Dec 2, 2023 · 14 comments · Fixed by #3072

Comments

@spydon
Copy link
Member

spydon commented Dec 2, 2023

What could be improved

The following is valuable feedback that we got from Google:

Feedback for Flame documentation

  1. It needs an introduction.

    • It lacks an explanation of what Flame is, what it does, how developers benefit.
    • The context for the entire ecosystem is missing.
  2. It needs context.

    • Each section of the documentation lacks any “why” regarding the need for or use of the particular section.
    • Without context, it makes the information less approachable.
  3. It needs conceptualization.

    • Each section lacks context for either Flutter or game development.
    • This could include references to Flutter via link or explanation as well as those for common game development concepts.
  4. It needs to be more atomic.

    • Some pages should be sections (especially Components and Effects).
    • These sections, when broken up, would be easier to find.
  5. It has links that need correction.

    • Some, like those at the bottom of Collision Detection, need to be fixed.
  6. It has URLs that include URL-encoded characters like spaces.

    • All of the examples have URLs with spaces in them. That should be fixed.
  7. It has many accessibility issues.

    • The color contrast between text and background is poor.
    • Many links lack usable text. (That is, they just link on the word “here”.)
    • Form labels and alt text are missing in places.

Why should this be improved

Because we want good docs.

Any risks?

No.

More information

If you would like to work on a big specific part we can split it out to a separate issue, if you just want to do a small fix related to this issue there is no need to create a new issue.

@siya100
Copy link

siya100 commented Dec 12, 2023

hey!!!@spydon
can you assign me this issue as i am interested in working on it

@spydon
Copy link
Member Author

spydon commented Dec 12, 2023

hey!!!@spydon
can you assign me this issue as i am interested in working on it

This issue is more of a list than one single issue, which part would you like to work on?

@siya100
Copy link

siya100 commented Dec 13, 2023

I would like to work on introduction part

@spydon
Copy link
Member Author

spydon commented Dec 19, 2023

I would like to work on introduction part

Sounds good, you can just tag this issue in the PR when you open it.
Here are some instructions for how to set up the docs locally:
https://docs.flame-engine.org/latest/development/documentation.html#building-documentation-locally

@siya100
Copy link

siya100 commented Dec 20, 2023

hey!!!
can you please ellaborate as its my first time contributing in documentation like which tech stacks are required.

@spydon
Copy link
Member Author

spydon commented Dec 20, 2023

hey!!! can you please ellaborate as its my first time contributing in documentation like which tech stacks are required.

It says in the instructions I sent.

@immadisairaj
Copy link
Contributor

I have started looking at the 5 and 6.

Seems like the links of examples (6) are automatic from the dashbook and so the spaces in the links. What could be done? (either change things in dashbook or update text in example to have _ instead of (which I don't think is a good way?) )

The issue in 5 - links are not links but texts in md file. So, they need to be fixed (with some understandable text)

@spydon
Copy link
Member Author

spydon commented Jan 29, 2024

Good to hear @immadisairaj!
I think the best way forward for those links is to change it in Dashbook, since that project is owned by us too it should be pretty straight forward.

@immadisairaj
Copy link
Contributor

I opened up an issue in Dashbook. I think once that is done, we can do (5) and (6) easily at a time.

@alt-shreya
Copy link
Contributor

Recenty came across this project and noticed the callout about accessibility issues. I'd love to tackle this! ✨
@spydon

@spydon
Copy link
Member Author

spydon commented Feb 20, 2024

Sounds great @alt-shreya!
Have a look at these instructions for how to get the docs up and running locally:
https://docs.flame-engine.org/latest/development/documentation.html#building-documentation-locally

@immadisairaj
Copy link
Contributor

immadisairaj commented May 18, 2024

Could we probably have a checkbox on what all have been done here? Would be easy to see what all are pending.

@ufrshubham
Copy link
Member

Could we probably have a checkbox on what all have been done here? Would be easy to see what all are pending.

I've converted it into a checklist, but I am not sure which ones have been already addressed 😅

@immadisairaj
Copy link
Contributor

I've converted it into a checklist, but I am not sure which ones have been already addressed 😅

5 and 6 are done by me. 😊 I am not sure of rest.. 😅

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants