docs(homeserver): Improve developer docs and readmes - #431
Conversation
d69de87 to
8236048
Compare
8236048 to
6b838c2
Compare
6b838c2 to
f2beec2
Compare
SeverinAlexB
left a comment
There was a problem hiding this comment.
I only reviewed the main README so far. Looking at the overall structure, it feels incomplete/thin.
Here are some AI recommendations edited by me on how to extend the readme with:
- No quick start command path. The README points to guides, but a first-time reader has no immediate “try it in 2 minutes” path. Even 3 lines linking to Docker Compose or local testnet would help.
- The repo scope is undersold. The README does not say what pubky-core is about. It is an attempt create a new internet, free from wallet gardens (see Johns vision). At the moment, the README does not say anything about it. It feels technically dry.
- No “who is this for?” split. There are at least three audiences: app developers using the SDK, contributors developing locally, and operators running a homeserver. The README would benefit from making those paths explicit.
SeverinAlexB
left a comment
There was a problem hiding this comment.
This is the INSTALL.md review
|
@SeverinAlexB The thinking was that intro information on the system as a whole should live only in pubky.org and linked to in the repo, which I hadnt done yet. I do however see the value in there being a short intro here aswell for those who have stumbled upon the repo without context, so i've added a paragraph with pointers to pubky.org. Im not sure about a quick start guide on the root repo. Quick start for what? development, running a HS, building an app? IMO better to link out to docs/guides immediately. I liked the idea of "who is this for" section so used that as a base for linking to the new guides on this branch. I also stripped down this core readme - its now just an intro with links to pubky.org and repo docs. |
4f0dc41 to
5ea010e
Compare
04b671e to
7e582af
Compare
| @@ -9,36 +9,20 @@ Two testnet types are provided: | |||
| | [`EphemeralTestnet`] | Random | In-memory | Automated tests (`#[tokio::test]`) - parallel-safe, no port conflicts | | |||
| | [`StaticTestnet`] | Fixed, well-known | In-memory or persistent | Interactive / CLI use - browser tests, mobile apps, manual debugging | | |||
|
|
|||
There was a problem hiding this comment.
This file i improved when i merged the recent StaticTestnet persistent data-dir changes. I made it match the guides by adding a ToC and troubleshooting section. Here I remove those in favour of keeping it as a developer-aimed crate explainer.
SeverinAlexB
left a comment
There was a problem hiding this comment.
The INSTALL.md is getting pretty good! I run everything on a new Ubuntu server and it worked flawlessly. I added some comments but the most feedback I got from an AI review. I tried to only add the AI comments that are necessary but feel free to just close them if you think they are trash.
…ief intro to ecosystem and codebase.
…el like the right fit for this guide in its current form
…stnet instructions. A couple review fixes.
7e582af to
db42219
Compare
|
The guides LGTM. Feel free to ask somebody else (outside of core?) for a review if you think it will be of benefit. Otherwise, we can merge I can't approve my own PR so this is my explicit PR approval |
GETTING_STARTED.mdandDEV_TESTING_GUIDES.mdwith two guides:INSTALL.mdfor operators andTESTING.mdfor devs.Ive attempted to keep things succinct whilst also ensuring to mention all available options and ways users may trip up. I think i found a good balance but please let me know your thoughts.
Not included: