ml5js / ml5-website-v02-docsify

This repository is a work-in-progress website, containing documentation and reference materials for the ml5.js library models.
https://docs.ml5js.org/
Other
1 stars 11 forks source link

Myrah bodypose content rewording #80

Closed myrahsa closed 5 months ago

myrahsa commented 5 months ago

Here are my (small) adjustments to @QuinnHe's bodypose content rewrite. Some changes:

  1. Consistent use of file names (i.e., "index.html" instead of "the HTML file")
  2. Structural changes - combined demo and quick start, renamed "how to" to "tutorial", and changed H4 to H3 where necessary
  3. Camel case when referencing model
  4. Reduce directional language
  5. The rest is mostly corrections to grammatical errors, eliminating redundancy when excessive, and minor adjustments to language just so things flow better

Other questions:

  1. Is it possible to change the color of bold text? It's very similar to the color of links which can be misleading.
  2. I wonder if we can shorten the code in the tutorial so that it doesn't feel too lengthy? Maybe only include the snippet that's being added after each explanation so it's more clear where the change is happening, and then including the full code altogether at the end (or beginning)? As opposed to the current version that is copying the entire code from the previous instructions and adding to it each time.

Anything you are not happy with let me know, and I can change it back! I know there's also some discussion around fixing the Methods section so feel free to add to that.

netlify[bot] commented 5 months ago

Deploy Preview for ml5-next-gen-docs ready!

Name Link
Latest commit d917544dd2880ab505712295b0b5ed309388470d
Latest deploy log https://app.netlify.com/sites/ml5-next-gen-docs/deploys/6669493b9c23310008555edd
Deploy Preview https://deploy-preview-80--ml5-next-gen-docs.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

QuinnHe commented 5 months ago

Thanks @myrahsa ! This is absolutely awesome! Several quick comments:

  1. Should we use “Multi-person detection” if we want to emphasize they can switch between Single person mode and multi person mode?
  2. I met with Moon, and talked about the naming of “How to”. He feel maybe we could consider something between “How to”(too simple) and “tutorial”(too strict). We can talk about it during today’s catchup.
  3. Another quick thing that not for body pose but for other model - if Myrah you find any terms you want to link to ml5 glossary, feel free to add a lightbulb tip. And anything you find should be covered by ml5 glossary but didn’t, feel free to share with @alanvww , Alan will help to add to the glossary.
  4. In terms of shortening the code in tutorial, yes, that’s something I hesitate as well. I feel it maybe tedious for readers to go back and forth to find where to add the line of code. Or we can use … to omit some redundant lines, and only leave the line right above and the line right below to save space. And definitely love your updates about adding function name in the instructions.

Let me know what you think!! cc @MOQN @alanvww hey Moon, Alan, any input from you will be greatly appreciated :)

@alanvww Hi Alan, I noticed Myrah made some small changes to “Methods” this section, feel free to pull from this PR to merge into your local. If you will rewrite the whole section, feel free to do so as well, we can always merge when you create the new PR. Looking forward!!

MOQN commented 5 months ago

Thank you all! Let's discuss this soon :D

MOQN commented 5 months ago

I would like to suggest three:

  1. I would avoid using the word "tutorial." It's already used many times on the page. "Tutorials" could be something more extensive, such as Dan's videos and some content in the Learn page. How about using "this", "this page", "this reference", or "this demo" in paragraphs?
  2. For the header "How to", how about "Getting Started Guide", "Step-by-Step Guide" or "Usage Instructions"?
  3. I would place "Examples" right after "Demo." They can be combined as "Quick Start." Then it is followed by "How to"