ScratchAddons
Documentation for addons
I have thought this for a while, but I forgot to create an issue here. So, here it goes.
There should be a section on the docs where every addon is documented, complete with the description, related images, better attribution, rationale, video/image demonstration, and so on. This is different that the Addons page, which is more simplified in mind.
This is like your usual Fandom wiki where each characters (and others) are described, but change the characters to Scratch Addons' addons.
I'm thinking to put this on /docs/addons/..., and this should work in tandem with https://github.com/ScratchAddons/ScratchAddons/issues/364.
This issue should focus on the framework of the documentation. The planning of the contents the page should come later, but we should discuss what is worth to include on the documentation.
@Hans5958 Good idea. So I guess each addon would have a very detailed description including why it was made, the github issue for it, and of course a very thorough explanation of what it is, etc.
@Hans5958 [completely edited] Having docs for all addons would be very nice, but I think it's simply a bit too much work. Instead, maybe there can be more stats and short bits of info such as the GitHub issue for it on the addons page?
To be fair, there is no priority for having each and every addon to have it's own fully descriptive page. I myself fine if we got missing pages. Also, cramping more information to an already long "Addons" page wouldn't be feasable.
There is no rush, so thinking high is fine.
@Hans5958 [completely edited] Having docs for all addons would be very nice, but I think it's simply a bit too much work. Instead, maybe there can be more stats and short bits of info such as the GitHub issue for it on the addons page?
I see what you're saying, but I don't think it would hurt to have pages on everything- there's no rush, after all.
Some ideas on what we could include on each page:
- Per-version changelog (only important changes, not just every commit that changed the folder - this wouldn't be automated)
- Motivation for the addon: why it was added, link to the issue that suggested it
- Browser/OS support, for example: Cmd instead of Ctrl key on Macs, gamepad support addon (what gamepads are unsupported), etc.
- Known issues/bugs with the addon
- More detailed explanation on each addon setting (we do plan to add the possibility to add these to the actual settings page at some point)
- Screenshots, of course
- Link to issues, PRs, and quotes of relevant suggestions, related to the addon.
- Only for editor addons: indicate whether it's available on TurboWarp
- "Related addons", which lists similar addons, or those which are usually used in conjunction
This "wiki" should be categorized into website, editor, themes, and popup addons.
@WorldLanguages In full screen settings and on the Addons page there should be a button or link that takes you to the corresponding wiki page of each addon.
Got time for a little bit of writing here.
For a while, I tried to think the parts of each page, and here's what I think is a good division. Keep in mind that each of these should be a section, and have it's section heading.
- Overview: ~~Description of the addon.~~ Simple explanation describing the addon in general. Probably don't need a specific heading, just like the lead section on Wikipedia.
- Background: Reasoning/rationale/motivation and/or history of the implementation/addition of the addon.
- Features: Explanation of the available features inside the addon.
- Usage: Explanation of how to use the addon.
- Settings: Explanation of available settings.
- Compability: Information about compability, or browser/OS support.
- Future plans: Future work that will be done.
- Known issues: Known bugs and issues presents, including a link to the issue if necessary. (can be merged to the previous?)
- Credit: Detailed credit/attribution.
- Changelog: List of changes for each addon. Ideally this should be divided per version.
- Trivia: Witty notes or interesting things related to the addon.
- Gallery: Videos, screenshots, and other media that can't be included directly on the page.
- Related: Links to related pages. This includes issues, PRs, docs or addon docs page, etc.
Also, I tried to think about the infobox that probably will be shown on the right side, just like Wikipedia infoboxes. The fields that will be included are as follows.
- Name*
- Tags*
- Should categories be it's own field?
- Should status based on here?
- Version added*
- Credits*
- Enabled by default?*
- Dynamically enabled?*
- Dynamically disabled?*
- Status (beta or stable)
- Available on TurboWarp? (probably)
* automatically from manifest
@Hans5958 LGTM! There are some minor details about the format that we could discuss, but it's not worth it. We probably won't notice what is lacking or unideal until we actually start writing the "wiki" pages, so I'd say we should start working on this.
We can still discuss since I don't think I'm doing this tommorow or the day after. Also, it is Markdown-based, so building the "engine" for it would be separate than the content.
EDIT: I think the one that is important to discuss now is about the tags? Should the status and category be separated and inferred for the tags? How would it inferred?
IMO, the category/tag model should be changed in the extension itself. It's a pretty confusing system that hasn't really changed a lot in 2 years. I'd suggest hardcoding the category into every doc page, but not the tags. Every addon has a single category/subcategory, so it sounds like the easiest option. EDIT: actually, addons can have multiple subcategories :P
By the way, I also see Scradd (the Discord bot) has it's own way to get infer the categories based on the tags. Should something like that be implemented?
I forgot: There is a good reference/example, right here:
By the way, I also see Scradd (the Discord bot) has it's own way to get infer the categories based on the tags. Should something like that be implemented?
IMO, we should manually type the category in each page, until the addon.json format is changed and automating the logic is easier. But, if someone wants to, they can try to automate this. I just think it's not worth it.
By the way, I also see Scradd (the Discord bot) has it's own way to get infer the categories based on the tags. Should something like that be implemented?
It uses the same logic as in the settings page. https://github.com/scratchaddons-community/scradd/blob/171e90c2d8e51637dfc5caddc76b9128f3aa4748/commands/addon.ts#L52-L74
A little bit of progress. More information will be added on the infobox later. Placement is now on docs and will be further considered later. First paragraph is just for debugging purposes.
Here's the screenshot. The significant change is the infobox, which now has more information, along with some using the badges from Bootstrap.
Some other consideration: Subpages can be created for something that is significant enough to warrant its own page, like a page for developing sake, for example.
EDIT: Or other sections that are long enough to have its own page, such as a expansive guide, instead of putting it below the "usage" section.
I've added a "Usage" section, and modify the "Overview" section to not depend to the description, because the current descriptions have something like how to use it.
Here's a first draft of the insert block by name addon's page. I changed a few things in the format though.
- I was struggling to differentiate the 'overview' and 'background' sections. It's kinda hard not to rationalize the existence of the addon when you're describe it, so I got rid of the 'background' section.
- I didn't include compatibility, instead moving it into 'Known issues'. I feel like most addons will have very little to write here and they are mostly issues anyways so I don't think an entire subheading is justified.
- I didn't write a section on usage because I feel that the information is succinctly covered in the overview and features sections.
- I'm not sure what to put under 'related', so I left it as a TODO
- We should also probably decide on a format for the settings section. I went for the name of the setting in bold with all caps (like they're shown in SA) followed by a description.
Additionally, we need to decide on the tone of these articles. I tried to go for user-friendly and was not referring to the reader directly but instead wording it more like a real wiki page.
---
title: Insert blocks by name
id: middle-click-popup
layout: addons
---
Insert blocks by name is an addon which allows users to code more quickly by typing the name of blocks and inserting them at their mouse position, rather than having to search for them in the flyout. The popup is opened by middle clicking in the workspace or pressing `ctrl` + `space`. You can then type to search for blocks and using the mouse to grab one out of the popup.
## Features
- The searching supports any block in the workspace. This includes custom blocks, blocks from extensions and variable / lists.
- You can use the arrow keys and enter to navigate the search results for even faster insertion.
- When a result is highlighted, you can press tab to autocomplete your search to that block.
- The popup can insert multiple nested blocks at the same time, by typing something like "move my variable + 10 steps".
- For mathematical blocks, the order of operations applies by default, but you can use brackets to change the order.
- You can surround text in double quotes to force the searcher not to turn your text into blocks. This is useful for sitruations like trying to say the text "x position" instead of the variable `x position`, where you could type say "x position".
## Settings
**POPUP BLOCK SIZE**
Controls how big the blocks inside the menu appear. It is the height in pixels of a single block.
**POPUP WIDTH**
Controls how wide the popup is. This is a percentage of the width of the entire window.
**POPUP MAXIMUM HEIGHT**
Controls how tall the popup can be before a scrollbar appears. This is a percentage of the hight of the entire window.
## Future plans
- The popup should be resizable by dragging one of the corners in the editor instead of having to change a setting.
- Adding string interpolation for strings in quotes could really help out situatoins where a lot of join blocks would normally have to be tediously arranged.
## Known issues
- The blocks inside the popup of this addon will not respect the settings from the *Customizeable block shapes* addon.
- The alogithm for sorting the search results still needs a lot of work, and sometimes the result you are probably looking for is hidden below a mountain of worse results.
- The "stop other scripts in sprite" block will look in the menu like it can't connect to other blocks.
- The "not" block cannot be put inside other triangle blocks like "and" or "or". "and not 1 = 2" will not work, but you can work around this using brackets, "and (not 1 = 2)" will work.
- Typing Emoji into the search bar doesn't show blocks containing that emoji.
## Credit
Tacodiva made most of the addon as it stands today. The original version was made by Griffpatch, which was moved by TheColaber from Dev tools into its own addon. Additionally, Griffpatch helped a lot by providing feedback and finding bugs in the overhauled version.
## Changelog
- **v1.30.0** The insert blocks by name addon was created.
- **v1.31.0** The addon was completely overhauled, allowing for nesting blocks, adding autocomplete and changing how the blocks where shown in the popup.
- **v1.31.1** The algorithm for searching was altered and several bugs where fixed.
## Trivia
- This was the first addon page written for the Addon Wiki!
- Despite only recently becoming its own addon, the middle click popup is one of the oldest features of Scratch Addons being a part of dev tools sense the beginning.
- The original code for the popup was created before Scratch Addons even existed by Griffpatch in 2019.
- When Tacodiva overhauled the addon for v1.31.0, the code had almost 2,800 lines of code added and 149 commits!
- The name of the Git branch for the overhaul was `idk-what-im-doing`.
- Tacodiva was struggling to fix an issue so much, that despite only contributing two lines of CSS to fix the problem, CST1229 is in the addon's credits!
## Gallery
TODO
## Related
TODO
Thanks for the draft! Few suggestions.
- I would prefer to have the features section to be a prose, not a list. Anything works, tho.
- The sections of the settings could be level 3 headers instead of bold text.
- The official name is "addon docs",
addon-wikiis just the branch name that I designate at that time. - You may link yourself if you pursue. I suggest to only link the first instance of your name.
As of the background, it could be oriented to something like the history of the addon. I saw that you mentioned that "the original version was made by Griffpatch". I would prefer this to be in the background instead.
PS. I have edited the message regarding the rationale of the sections.
I'm not sure for how long we'll display the setting names in UPERCASE in the settings page. So I think we should be using the addon.json names for the settings which do differentiate uppercase from lowercase 🤔