Edit docs for accessibility

[nickmcintyre]

Addresses #6483

Changes:
I edited the inline docs for describe(), describeElement(), textOutput(), and gridOutput() to bring them more in line with the style guide.

@dkessner, @MsQCompSci, @davepagurek, @limzykenneth, @Qianqianye, @katlich112358, @calebfoss, @cosmicbhejafry, @apoorva-a98, @tedkmburu, @Zarkv, @SkylerW99, @itsjoopark, @hannahvy, @nhasalajoshi I'd love to incorporate any feedback you may have! Here's a staging version of the edits in this pull request.

PR Checklist

• npm run lint passes
• [Inline documentation] is included / updated

[MsQCompSci]

In gridOutput the first example is missing the draw function like in the others. Maybe adding an example when gridOutput is used (instead of textOutput). It is also unclear to me, even after reading these docs, why someone would want to use textOutput over gridOutput, and vise versa.

[nickmcintyre]

@MsQCompSci thanks for pointing out the missing draw() function. Any example code that doesn't have setup() or draw() is placed inside setup() behind the scenes.

Should we generally use setup()? I revised the examples in this pull request to do so.

I updated the descriptions of gridOutput() and textOutput() to clarify when to use each. They also link to our new labeling guide. The staging version is updated. Let me know how these revisions look to you.

[davepagurek]

Should we generally use setup()?

I think the examples that don't use setup/draw are useful for showing very concise examples without boilerplate potentially distracting from the concept, e.g. to show a number of examples with the different parameters for the same function without the page getting super long.

In general though, I think it's helpful having at least one example with the full boilerplate so that readers know what part of their sketch to add the function to. Maybe it would be most consistent to always do drawing in a draw call but use noLoop() in setup to indicate that it will just draw once? But it's also valid to do drawing in setup, so I think what you've got now is also ok.

[nickmcintyre]

@davepagurek @Qianqianye if these changes look good to you, please go ahead and merge them.

[Qianqianye]

It'd be helpful to add a comment here to explain what frameCount % 100 does in the code

[Qianqianye]

The original description shows that users can use variables like 'x' within describe(). I think it's helpful to show this use case. What do you think? @nickmcintyre

[Qianqianye]

Would it make sense to show textOutput(LABEL) in one of the example snippets?

[Qianqianye]

Would it make sense to show the gridOutput(LABEL) usecase in one of the example snippets?

[Qianqianye]

Would it make sense to explain the use case of using both textOutput() and describe()?

[nickmcintyre]

Great suggestions @Qianqianye. Please let me know how the latest revisions look.

[Qianqianye]

Thanks @nickmcintyre, great work! I just merged it. Just to take a note for our backlog, some of labels in the example code are quite long, which takes up a lot of vertical space. We can revisit this after the web redesign phase.