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.

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

Feat: Add documentation site using Docusaurus #2358 #2359

Open
wants to merge 5 commits into
base: develop
Choose a base branch
from

Conversation

ikoenigsknecht
Copy link
Collaborator

@ikoenigsknecht ikoenigsknecht commented Mar 12, 2024

This adds Docusaurus to Quiet, enabling us to have a fully-featured documentation site locally or deployed to production.

I did my best to migrate existing documentation from the markdown files in the repo (including the README) but I'm sure I missed something. I also added some documentation on how Docusaurus works and is configured with links to the official docs.

Styling is a rough first try with Quiet colors but we can certainly iterate on it.

Here are some screenshots so folks can get a feel for the styling/setup:

Screenshot 2024-03-12 at 10 58 50 AM Screenshot 2024-03-12 at 10 59 00 AM Screenshot 2024-03-12 at 10 59 34 AM

Pull Request Checklist

  • I have linked this PR to a related GitHub issue.
  • I have added a description of the change (and Github issue number, if any) to the root CHANGELOG.md.

(Optional) Mobile checklist

Please ensure you completed the following checks if you did any changes to the mobile package:

  • I have run e2e tests for mobile
  • I have updated base screenshots for visual regression tests

@ikoenigsknecht
Copy link
Collaborator Author

Implements #2358

@ikoenigsknecht
Copy link
Collaborator Author

NOTE: Much of this is boilerplate generated by Docusaurus, if you have any questions about anything reach out!

@holmesworcester
Copy link
Contributor

This looks great! I think we might want to go a bit further in consolidating docs. Right now it looks like there are duplicates to files like CONTRIBUTING.md and there's a separate docs folder. My worry is that someone might update the docs in either place, leading to lost or conflicting updates. Would you like to propose some consolidation?

@ikoenigsknecht
Copy link
Collaborator Author

This looks great! I think we might want to go a bit further in consolidating docs. Right now it looks like there are duplicates to files like CONTRIBUTING.md and there's a separate docs folder. My worry is that someone might update the docs in either place, leading to lost or conflicting updates. Would you like to propose some consolidation?

Originally I was gonna delete those but I noticed that at least some are referenced on the website and didn't wanna break things.

@holmesworcester
Copy link
Contributor

holmesworcester commented Mar 12, 2024

Then I think we should either:

  1. leave them out of Docusaurus so we do not have to update both.
  2. update the existing files to not have any content and refer people to Docusaurus.
  3. Remove them and update links as best we can.

For README.md I think we should definitely do #1, since everyone would expect to find a README, and because the Github project page content comes from this.

Some context on this is that it's very easy for the development instructions to fall out of date when somebody makes changes, it's somewhat hard to catch this systematically because internally we always know "the trick" to get things working, and it's always discouraging for new volunteers to follow our instructions and run into a problem because they're out of date. So we want to avoid having two sets of instructions because then we have even more ways to fail to update the instructions correctly.

We're also using the Github Wiki for docs and page content. How do you think we should integrate that? One solution here would be to distinguish between developer-facing docs and public-facing docs like the Threat Model, and move all developer-facing docs into Docusaurus, but keep others in the wiki. How does that sound?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants