README and rustdocs mirror

[mehmetefeumit]

Currently, the README (which is used as the landing page file) and the rustdoc main page of this repository do not match, and there might be information we want to display in both as the project is approaching a 1.0 release.

Current State

README has:

• 1-2 sentence summary for each crate in the repository.
• Disclaimer for missing independent security audit.
• Development status:
  • Stages of sender/receiver versions.
  • Development done and pending for receiver/sender.
  • Overall check-list for code quality.
• MSRV
• Reference to CONTRIBUTING.md.
• License.

rustdocs main page has:

• Only a 1-2 summary of the rust-payjoin crate.
• Mention of the v1 and v2 features, and that the library requires no IO (there is no IO by default unless explicitly turned on via io feature).
• Mention that types relevant to Payjoin Directory are available in the "directory" module and enabled with the directory feature.
• Disclaimer for missing independent security audit.

---

Instead of having to keep both pages up-to-date, my proposal is to (1) edit the README file so that it contains information which is useless in both GitHub and rustdoc, and (2) did what for example BDK does here where the rustdoc page is the README file.

The README should contain the most essential and accurate information from the two listed above:

• Summaries of each crate available in the repository.
• Explanation of the features enabled by default, and which feature should be enabled for what.
• Disclaimer for the missing independent security audit.
• MSRV.
• Contribution guide reference.
• License.

Things I need to get more information on:

1. Are we comfortable with removing the development checklist now that most are complete, and mention if there is anything missing in the relevant part (i.e. fuzz testing around the disclaimer), or create issues where applicable?
2. What is the best way to have examples for people unfamiliar with Payjoin? I'm thinking it would be too long to include in a README, so perhaps the https://payjoindevkit.org/tutorials/send-payjoin-with-pdk.html page can be updated to include up-to-date receiver and sender code.
3. Anything else to have in the final README before 1.0?

[spacebear21]

I agree with this mirroring direction, less places to maintain documentation is good.

Are we comfortable with removing the development checklist now that most are complete, and mention if there is anything missing in the relevant part (i.e. fuzz testing around the disclaimer), or create issues where applicable?

Yes

What is the best way to have examples for people unfamiliar with Payjoin? I'm thinking it would be too long to include in a README, so perhaps the https://payjoindevkit.org/tutorials/send-payjoin-with-pdk.html page can be updated to include up-to-date receiver and sender code.

It would be nice to update that page so it's correct but I feel like it inevitably ends up falling out of date. Maybe the README should include/link to an even simpler explanation of what payjoin is, perhaps an illustration/mempool.space example?

Anything else to have in the final README before 1.0?

Not directly related but I figure this is a good place to mention it: there are individual READMEs for each sub-package that will need a closer look as well. I recently noticed that the READMEs in language bindings end up getting published to their respective package managers, e.g. https://www.npmjs.com/package/payjoin, but that README was written with local dev in mind, not for downstream consumption.