Documentation Improvements

[spydon]

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]

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

[spydon]

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]

I would like to work on introduction part

[spydon]

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]

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

[spydon]

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]

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]

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]

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]

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

[spydon]

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]

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

[ufrshubham]

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]

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.. 😅