Documentation for addons

[Hans5958]

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 ScratchAddons/ScratchAddons#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]

Related: ScratchAddons/ScratchAddons#5091

[penguinmoose]

@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]

Right, if people have time to do so, that is.

[penguinmoose]

@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?

[Hans5958]

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.

[BroJac5246]

@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.

[penguinmoose]

@Hans5958 True. We can start now.

[WorldLanguages]

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.

[Secret-chest]

website, editor, themes, and popup addons.

player too

[penguinmoose]

@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.

[Hans5958]

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

[WorldLanguages]

@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.

[Hans5958]

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?

[WorldLanguages]

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

[WorldLanguages]

whoops

[Hans5958]

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?

[Hans5958]

I forgot: There is a good reference/example, right here:

• Microsoft PowerToys docs

[WorldLanguages]

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.

[Hans5958]

Ah, I see. I will think about it again later.

[Hans5958]

Related: ScratchAddons/ScratchAddons#475

[RedGuy12]

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

[Hans5958]

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.

[Hans5958]

Hereby is the edits that I can do based on what I known. The source can be obtained by the "Quote reply" button.

• I changed the headings and the case for the settings
• I renamed it to "Addon Docs." Whether to do "addon docs" or "Addon Docs" is up for debate.
• I separated the parts from Credits to the Background, and adjust it. I'm not sure whether what I wrote is really true, so please edit it if it isn't.
• I didn't put the links to Tacodiva (I'll pass it to the next editor).

Content

---
title: Insert blocks by name
id: middle-click-popup
layout: addons
---

Insert blocks by name

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.

Background

The original version was made by Griffpatch for the Developer Tools extension. As part of a work to separate features from the Developer tools as individual addons, this addon has been made to its own addon.

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. 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 Docs!
• 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

Something to consider:

• How to refer the other addons? The changelog use quotation marks but we can do better as a documentation. I saw that draft uses italics, and I think that's a good idea, but what do you guys think?

[DNin01]

• How to refer the other addons? The changelog use quotation marks but we can do better as a documentation. I saw that draft uses italics, and I think that's a good idea, but what do you guys think?

Another reason to change how we name our addons.

Otherwise, italics seems okay.

[WorldLanguages]

How to refer the other addons? The changelog use quotation marks but we can do better as a documentation. I saw that draft uses italics, and I think that's a good idea, but what do you guys think?

Wouldn't all addons be links to their respective page? In that case, we wouldn't need to choose a format for them, they would look like links, right?

[WorldLanguages]

I agree on using italics for addons that no longer exist, have been renamed, or can't be linked to for any reason.

[BroJac5246]

How to refer the other addons? The changelog use quotation marks but we can do better as a documentation. I saw that draft uses italics, and I think that's a good idea, but what do you guys think?

Wouldn't all addons be links to their respective page? In that case, we wouldn't need to choose a format for them, they would look like links, right?

Should we choose that addon names should be italicized, then, from an English language perspective, this should technically apply to links as well. However, should addon names be italicized in the first place? Italics are for longer works and quotes are for shorter works. Drawing an analogy, one would expect Scratch Addons to be italicized and "Addon name" to be quoted. We don't even use title case for addon names, so using the formatting for a larger work doesn't really make sense.

[Hans5958]

A refresh. Here's how it looked like today.

[WorldLanguages]

Will the addon articles share the sidebar with the rest of the docs? I can see the pages tree become really long. Also, does it really make sense to have user-facing docs and developer docs merged?

[Hans5958]

That might be a good point, and with clear separation the section, I think it's fine.

[Secret-chest]

For known issues we might want to link a github post.

[Hans5958]

It's been a while, but I wanted to keep tabs if people are still interested in contributing this. Otherwise, the docs would still empty after months upon merging.

[Samq64]

I could add a page or two but it'll take a while to fill them out properly.

[BroJac5246]

I wouldn't be against helping, especially with mine, but it's not like anyone can fill out a large portion of them at once.

I vote we just create "stub" wiki pages that say we'll add details soon, and then maybe require a new page to be included with each new addon?

Also do we want these to be translated? That would take a ton of work so probably not.

[rmHawk765]

I would definitely be interested in writing a few pages. As for translation, I think we shouldn't worry about it for now as it is nowhere near as easy as translating strings in add-ons, and managing everything would probably be more complicated as well.

[WorldLanguages]

Also do we want these to be translated?

Probably not.

[Hans5958]

Also do we want these to be translated? That would take a ton of work so probably not.

I'll just open it for translation and somehow they will come for translate it (or not, but that's because there are no deadlines, or contracts).

[DNin01]

Also do we want these to be translated? That would take a ton of work so probably not.

Ideally, we would, but it's a big task. However, we could always try opening up for translation requests and see what happens, especially if the documentation starts small.

We probably won't create very many articles that quickly, so hopefully the translation team wouldn't be overwhelmed. Writing articles at a pace at which the translators can keep up might help make it happen. I would probably enjoy doing a translation or two every once in a while when I've got nothing else to do, if I became fluent in another language.

[Hans5958]

Tried to merge the addons page with the docs, converting the page into the home of the docs (or the section)

/addons/

/addons/middle-click-popup/

[Hans5958]

Or, do you guys prefer with heading or no heading on each page? For the note, this is with the heading.

[BroJac5246]

Or, do you guys prefer with heading or no heading on each page? For the note, this is with the heading.

Is the "Addons" text the heading? If so, it seems like a waste of space so I vote we don't include it.

[Hans5958]

Is the "Addons" text the heading?

Yes. Compare it with the second image on the post before it.

[rmHawk765]

Or, do you guys prefer with heading or no heading on each page? For the note, this is with the heading.

Honestly it looks quite ugly and is a waste of space. But we could definitely put something similar in the navigation bar, maybe next to the logo with a separator?

[WorldLanguages]

It looks better without heading IMO.

[Hans5958]

I see a plenty of interest here. Yeah, never would I expect for the docs to be completed in one or two days. That would be stupid.

A question before I merge it or some sort: What do you guys feel about merging it now, minus the placeholders and the TODO text, which I think would be replaced with an admonition**?**

About the heading, I won't add the heading, then.

[BroJac5246]

I see a plenty of interest here. Yeah, never would I expect for the docs to be completed in one or two days. That would be stupid.

A question before I merge it or some sort: What do you guys feel about merging it now, minus the placeholders and the TODO text, which I think would be replaced with an admonition**?**

About the heading, I won't add the heading, then.

My take is that it has to happen at some point so why not now?

[Hans5958]

Alright, I think I did everything that makes it ready to be merged. I also added Addon Docs in this repo's wiki for future reference. Reviews are welcome on both issues.

For the note, #389 is ready to be merged.

[Hans5958]

As a reference, here's the current view. I just added shortcodes as templates for the docs in general, not just the Addon Docs.

[Hans5958]

Merged. Now, you guys can start adding pages. If you want to add stubs, go ahead, even on all pages.

I would say I welcome outside reviews, approvals, and change requests. This should make it easier for validation.

Don't forget to read https://github.com/ScratchAddons/website-v2/wiki/Addon-Docs.