Plugin Docs (READMEs) and website co-location

[thescientist13]

Discussed in https://github.com/ProjectEvergreen/www.greenwoodjs.dev/discussions/104

^{Originally posted by **thescientist13** October 6, 2024} Now with the project getting its own dedicated website repo, one thought I had was what to do about the docs (README's) for all of our plugins? Should we continue to keep that content close to the code? Or should we have all the content on the website and just have the README docs links to the website? So I guess it comes down to... 1. colocation for maintainers (keep things the way they are), or.. 1. colocation for users (have _all_ docs on the website) ---- My guess is that since all docs are already on the website, it would probably make sense for everything to follow the same convention, since I can't think of a super strong reason not too, aside from some basic convenience, but at the expense of users / readers.

[DevLab2425]

JSDocs for the maintainers, with generated output for the users? Typically there's a line between what the engineers need to know, vs. what the end-user needs to know. The crossover is where the JSDocs might be helpful, at least to start. Along with using the @private or @internal` tags, the output can be isolated to only the public API.

Docs are along side the code, and the curated generated docs can target other users.

As an example, consider the details around each-and-every Type in a library like Webpack. The end-user doesn't have docs for all of it, but it might be important for maintainers to know what's going on in the JSDoc comment / intellisense.

Just my 🪙 🪙

[thescientist13]

Good thoughts, thanks for sharing!

Yeah, I've been thinking about this for Greenwood (and TypeScript support overall) since it doesn't really have many APIs that actually introduce themselves into userland, other than the good point you make about plugin(s) (development), greenwood.config.js, and now our content as data APIs. Maybe you can share more thoughts in this issue, since I think that would apply more specifically to project, and not the docs website per se.

(This particular issue is specifically about where the current content for our plugins should live; in the website and the package README, which is what we'll have in place when we launch this new website, or just on the website, and thus the README pages would just link to the website.)