There's really not enough info in Readme.md

[mzso]

It doesn't provide any information on usage. That I have to search for a button of unidentified appearance and click it. Of course this means the button's appearance is not shown either. So one needs to resort to a lot of guessing and/or googling.

[JustOff]

Sorry, but at the moment I do not have enough free time to deal with this issue.

[RainerBielefeld]

Well, it would be very easy to add some information to the README.md. mzso, may be you can contribute some "How to use.md", so that JustOff simply has to add the chapters? If JustOff agrees with such a proceeding?

[JustOff]

In fact, I'm not sure if this is necessary at all, but if someone creates a really useful FAQ, I can add it in the repo and link it from the README.

[Andy2No]

I believe it would be useful to add this information, as in the issue I opened today #55 .

Also, by closing an issue, you effectively hide it - making it much less likely that someone will find that a relevant issue was already opened.

Feel free to add any part of what I wrote, to the readme.

[JustOff]

I appreciate your desire to help, nevertheless, I still believe that there is no need for additional instructions, given that the installation of the extension is completed by adding a new button to the browser panel, and everything further is quite obvious.

[Andy2No]

I think this is a case of it being obvious to you, as the creator, but not necessarily for potential users.

I came to this looking for a way to add a translate extension, that still works, in Waterfox. I found your project after extensive googling, but had not read how it worked, in the process.

So, I arrived here still expecting to find an archive of add-ons, which I could browse, looking for add-ons that were likely to be suitable for me. I didn't expect to have to install an extension which then gave me access to an archive of extensions - and having read your "readme", I was still none the wiser about what to do, or how it worked.

In short, you understand how it's meant to work, so it seems like an adequate explanation, but unfortunately, mostly to you.

As this has only been discussed in closed issues, the chances of someone finding the discussion is also quite small - evidenced by me not finding this topic before I posted a new one.

I agree with the OP - the readme needs more information. Specifically, it needs an explanation of how the extension is used, and how the contents (archive of add-ons) can only be seen after installing it. That's not clear, at all, as it stands.

[garoto]

I think this is a case of it being obvious to you, as the creator, but not necessarily for potential users.

Go to release page; see a .xpi file listed:

gee, I wonder what that is supposed to be

Legit mind-fuckery.

[Andy2No]

Not helpful, garoto, and I am not the first person to point out that the documentation isn't enough, for people who actually need to read it.

[garoto]

Ok, here's an idea: why don't you submit a pull request for the readme.md with your quality-of-life improvements.

[Andy2No]

I already provided some additional wording, in issue #55

I am happy for anyone to use all or part of what I wrote, without giving credit for authorship, in this or any fork of the project. If someone wants me to expand on that, or précis it to a shorter version, I am happy to help with that too.

[mzso]

@garoto commented on 2019. máj. 2. 22:19 CEST:

I think this is a case of it being obvious to you, as the creator, but not necessarily for potential users.

Go to release page; see a .xpi file listed:

gee, I wonder what that is supposed to be

Legit mind-fuckery.

Half the people wouldn't even know what an xpi is. They're just used to clicking the big install button on AMO.

[garoto]

Half the people wouldn't even know what an xpi is.

With such irrefutable real world numbers, I guess you must be absolutely right.

I just wonder why all those 214 people who starred this niche project on github didn't complained earlier. Weird.

[mzso]

@garoto commented on 2019. máj. 3. 03:41 CEST:

Half the people wouldn't even know what an xpi is.

With such irrefutable real world numbers, I guess you must be absolutely right.

I just wonder why all those 214 people who starred this niche project on github didn't complained earlier. Weird.

Is there anything more petty than fixating on a figure of speech? Instead of a half-argument even.
...

[JustOff]

Please don't get me wrong, but with all due respect, those who cannot figure out how to use this archive will most likely not be able to get any benefit from its contents, because using legacy extensions requires a slightly higher level of knowledge than the ability to click on the big install button.

[mzso]

@JustOff commented on 2019. máj. 3. 11:54 CEST:

Please don't get me wrong, but with all due respect, those who cannot figure out how to use this archive will most likely not be able to get any benefit from its contents, because using legacy extensions requires a slightly higher level of knowledge than the ability to click on the big install button.

I quite disagree.
People who want classic addons, will likely find Waterfox/Pale Moon/Basilisk, just by googling.
Where it's no problem installing and using XUL addons.

*But here they have to figure that this is an addon that needs installin, because not even that information is provided in the readme.
*Then they have to realize that an xpi means an addon that they can install. Which based on AMO *experience experience won't be obvious.
Then they need to figure out how on earth to use it, because nothing obvious happens when it's installed.

This last one caught even me out for a minute. Nothing obious happened. So I went into about addons. No options here. So I started looking for options, buttons appearing which were in no way specified and nowhere did I see how the button is supposed to look. (I have a lot of buttons and happen to have an orange one near where it appears by default)
Subsequently the button disappeared for an unknown reason. And I only found out that there was a tools menu item, after asking here.

If only the readme showed what the button looks like and make note of the menu item.
And would provide an "install addon .xpi here" note/link. It would make it easier for people and you as well, by not getting superfluous issues opened.

[endolith]

So two people have tried to get you to add basic documentation for your add-on and you refuse for no reason? You want your users to be confused? This is ridiculous.

[garoto]

Various "Add-ons" used the "tools" menu (and only that) in legacy Firefox to make themselves visible to the user. It is/was very common. Not sure what this commotion is all about.

[endolith]

@garoto Those Add-ons also had instructions on how to use them.

The Tools menu doesn't even exist anymore. You have to press Alt+T to get the menu bar to display, which is otherwise hidden by default, since you're supposed to use the new hamburger buttons thing. I have the menu displayed on my browser, because I'm used to it from the old days, but most don't.

This is an archive of legacy add-ons. It's not at all obvious that this would 1. Install an extension of its own, that 2. You then have to find in your Tools menu, which 3. Opens a new window that displays a page that imitates a defunct website, which 4. You can search inside to find XPIs to install.

How would anyone be expected to know any of that without instructions?

I expected it to provide an Options button in the about:addons listing for the Add-on, like other extensions do, but instead it makes a listing in the Tools menu. That's perfectly fine, it's just non-obvious.

because using legacy extensions requires a slightly higher level of knowledge than the ability to click on the big install button.

No, it really doesn't. Even if it did, that would be an argument for more documentation, not less.

I can understand not being bothered to write instructions for something that you perceive as obvious because you wrote it, but to refuse to include instructions that other people wrote for you because multiple technically-skilled people have been unable to figure out how to use the thing is totally bizarre. (#65 (comment) #56 #55 #45 #44 #26)

As far as I know, the list of Pros and Cons for including documentation for your software is:

• Pros: People know how to use your software and stop bothering you with the same questions
• Cons: There aren't any cons.

Am I missing something?