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.

Sign up for GitHub

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

Jump to bottom

Update README.md #75

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update README.md #75

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 9 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# ProjectDiscovery Documentation

<h4 align="center">
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

This is the source code for the ProjectDiscovery documentation located at https://docs.projectdiscovery.io
This is the source code for the ProjectDiscovery documentation located at https://docs.projectdiscovery.io.
</h4>


Expand All @@ -19,26 +19,24 @@

---

## Development
## Build docs locally
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


1. Checkout this repository
1. Install mintlify with `npm i -g mintlify@latest`
1. Run `mintlify dev`
1. Fork this repository.
1. Install mintlify with `npm i -g mintlify@latest`.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Also, does the user ever need to update Mintlify?

1. Run `mintlify dev`.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?


## Deploying
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


To build the final product, we have a couple of additional steps:
To build the final product:

1. Build the JS Protocol Docs
1. Build the JS Protocol Docs:
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


- `npm install -g jsdoc-to-markdown`
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

- `./bin/jsdocs.sh`

2. Build the PDCP API reference documentation
2. Build the PDCP API reference documentation:
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


- Either download the latest `openapi.yaml` manually or run `./bin/download-api.sh`
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

- Run `./bin/generate-api.sh` to generate any new API files

3. Deployment

After those, Mintlify handles the deployment automatically.
3. Mintlify handles the deployment automatically.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.