Update README.md

[oddlittlebird]

Minor edits and a bunch of comments for the README. Documentation fixes are a great way for new contributors to participate and learn about a project, so you want it to be as friendly as possible.

TL;DR - You guys are missing a lot of information. I recommend:

• Create a CONTRIBUTING file and link it from the README. This file should include any guidance for actually writing the docs, including links to a style guide if you have one.
• The first set of numbered steps is for running Mintlify and building the docs locally, not how to actually write docs.
• Information is missing, like, will Mintlify automatically open in development mode? Do I need to do something to trigger a fresh build? What else does someone new to this project need to know?
• I see a bunch of manual building tasks that are done locally in the Deployment section.
  • Why are these not done automatically with GitHub actions or on a server?
  • Is the user supposed to upload changed files to Git and merge them after they are built? You do not actually specify.

[oddlittlebird]

Added comments and questions.

[oddlittlebird]

This combination of markdown and HTML is really weird. I suggest just using markdown.

[oddlittlebird]

You should have a separate section or separate topic with guidance for actually working on these docs.

[oddlittlebird]

npm should be listed in a Prerequisites section, along with installing mintlify.

Also, does the user ever need to update Mintlify?

[oddlittlebird]

Where do they run this? Root level of docs folder, I assume? Also, where will the docs build show up? Does it go to a default port in their default browser? What should they expect?

[oddlittlebird]

Unclear what you are deploying. Do you mean "Deploy updated files"? "Deploy new documentation"? And where is it getting deployed?

And when all this is done, how do you get files from your local fork back to the main project? (Assume you are talking to a technical writer who wants to get some practice in open source. This is super common.)

[oddlittlebird]

Do you mean JavaScript? If so, spell it out on the first use.

[oddlittlebird]

As above, where do you run this? And do they have to be separate commands, or can you run them together? If you can run them together, then why aren't they in a code block?

[oddlittlebird]

Remember, whoever is running this might be new to the project. Tell them what PDCP API documentation is, preferably in the section about actually working on docs, which does not yet exist.

[oddlittlebird]

Download from where? And couldn't this be automated in a makefile or something?

[oddlittlebird]

As a user, this does not tell me how I know if the deployment is successful, or what to do if I don't see updated files.