-
Notifications
You must be signed in to change notification settings - Fork 29
WritingDocumentation.md
Scarpe has its README, it has API Docs, it has this Wiki, it has old Shoes docs and there's no reason it couldn't have even more.
There's also a difference between Scarpe's top-level documentation and various other related repositories.
Scarpe's README is a top-level landing page for new folks who have just found us. It's a summary for folks that know about us coming back. It's a statement of philosophy for people who wonder why they should care.
We want to quickly summarise interesting topics there, then point somewhere else (Wiki, API docs, Shoes manuals, etc) for deeper detail.
It's edited in the usual way with pull requests.
There are Scarpe-related projects in the Scarpe repo (scarpe-components, lacci, arguably scarpe-webview.) There are also varyingly Scarpe-related projects outside the main repo (scarpe-wasm, wasify, webview_ruby, outdated: scarpe-folio.)
These READMEs are also potential sources of information, and may be a good place to put in a PR, especially if something is outdated, unclear or just doesn't mention things it should.
We use YARD for Scarpe API docs, and build them automatically via GitHub Actions.
You can also run the "yardoc" command locally and browse them on your local machine.
You'll normally change those via PRs where you add or change comments. Occasionally we'll want to change namespaces, method names or other actually-runs-as-code things to improve our documentation.
API docs are a great place to put information that changes infrequently -- what classes are in Scarpe and how they work, for instance -- and that tends to change when the code changes. So we store them with the code, and require approval to change them, just like that code.
The Wiki can be a rich source of random information. It's great for information that doesn't belong next to the code and/or doesn't change when the code changes. For instance, history of a Hack Days isn't directly about code. How to contribute to the project isn't directly about the code. Design philosophy can sometimes belong in the code, but usually it's more conceptual than that and there's no obvious place to put it in the code.
All of those things are good candidates for "put it on a wiki page."
The docs/static directory in the repo contains older Shoes manuals, mostly from the "Red Shoes" and _why era, long before Scarpe was written. That's good! We want Scarpe to be compatible with that! But also we don't go in and change them when Scarpe changes.
It would be reasonable to have a Scarpe-specific manual with useful writing about Webview and Wasm and what Scarpe does and doesn't support. But we don't really have that in manual form. You could write one? Or just a small blog post, chapter, etc?