zzz.i2p

Development discussions
 
Sun, 24 Jan 2021, 02:16pm #1
zzz
Administrator
Zzz

@idk you're going through recently and renaming addressbook, eepsites, ... but you've never posted a glossary/style guide for others to use or even review.

iirc we talked about it a year and a half ago but nothing ever happened. Maybe something was pinned in mattermost, can't remember.

If you have a plan or have made a bunch of decisions, please post it, so we aren't going in opposite directions. For address book, maybe we already are? can't remember.

It's important to have consensus because every change breaks the translations.

edit: looked on my hard drive for any style guide I may have started, can't find anything so far...

Last edited: Sun, 24 Jan 2021, 02:41pm by zzz

Mon, 25 Jan 2021, 05:49pm #2
idk
I2P Legend

Ack, this indeed grew out of a style guide we started a year or two ago but which did not finish, and actually sort of turned into a proposal to make some changes to the addressbook for 0.9.50, so it's a good time to talk about the rest and also take you through the whole thought process. There is less ambition to just change many things arbitrarily, only a handful of changes with acceptable justifications are really important-seeming, and those are the only targets. Most of these will happen around the Hidden Services Manager and the Address Book, with the goal of changing terms to things that increase:

- The self-evidentness of the definition of a term. If it's possible to just say what a thing is, then say that first. For example, the change from eepsite to I2P Site. Other places where people had issues with terminology are not quite so simple, I'll go more into depth a little further down, but there are some tough descriptive nuts to crack in the Address Book.
- The formality of a term. Portmanteus, contractions, slang, etc. have been generally discouraged some of the people who conducted the usability studies, etc. Technically "Addressbook(Here Firefox goes underlining it in red)" fell into this category, however the reason it got changed first was that there were lingering usages of different spacing, capitalization, so it got done first. The reason "Address Book/address book" seemed like the best choice, because it seems the least prone to misusing spaces/casing.

We might have been working in opposite directions on Address Book, I wasn't aware. That's my reasoning for the two-word address book though.

The remaining proposed changes will mostly affect the Hidden Services Manager and the Address Book.

Hidden Services Manager
-----------------------

The Hidden Services Manager is pretty good on self-evidence, although the name itself(Hidden Services Manager) is reportedly intimidating to new folks, we set up the default tunnels they need. The name of the Hidden Services Manager does not need to change.

Tunnel Wizard: This has the problem of feeding into a perceived ambiguity of tunnels vs tunnel pools vs hidden services, making it less self-evident than it seems. A more self-evident term might be "Service Wizard," "Application Setup Wizard," or "Proxy Wizard." Wizard itself isn't actually a great term either, although it pains my beard to say it. Guided Setup would be more self-evident.

Streamr Tunnels: Nobody knows what these do. There are probably people who have written SAM libraries because they didn't know what streamr tunnels do. There is also another project that is using the name Streamr, and they have all the search results. They should be changed to Datagram or UDP tunnels.

Standard Tunnels: Pretty minor and not something I am going to push hard on, but "Standard" client and server tunnels may benefit from having differentiated names. For example, a "Standard" server could be a "General" server or a "Streaming" server, and a "Standard" client could remain the same. This may have made things a little more obvious for the XMPP server guy: http://zzz.i2p/topics/3015-openfire-xmpp-server...

Address Book
------------

AddressBook: Address Book itself had lingering mixed usages and used a contraction that was ambiguously identified as a misspelling. I already explained my reasoning for the use of 2 words for Address Book, but I did consider all the different forms of it which were present. The other reasonable-seeming choice was "Addressbook" without book capitalized in titles, and "addressbook" all lower case in sentences/paragraphs, because this was the version which was used most when I collected usages of various forms of Address Book in the UI.

The Address Books Themselves
----------------------------

All address books have sort of the same underlying meta-issue with terminology, which is that nobody seems to agree or intuit what the different address books are supposed to be useful for and how to actually use them, and in practice everybody makes their own rules for how to use them. For example, some people use the "local" address book to store sites that they are hosting on the same computer where the address book resides, whereas other people use the "Local" address book to disambiguate addresses that they added using a jump service from addresses which were added by a subscription. Still others have more sophisticated behaviors, carefully choosing the "Private" and "Local" addressbook depending on whether they believe the address they are about to visit is going to be something they wish to help others access, or which they prefer to keep secret, but leaving them with no way to disambiguate services they host themselves and services they added with a jump unless they cross-reference it with hidden services manager. Maybe all of this is "OK," Address Book is very flexible after all, but it makes it very hard to give advice on how to use the address book and silently forces decisions upon users who do not fully understand what they want to use the address books for going in.

Local Address Book: Depending on whether it's for "Sites I host" or for "Sites I added manually and wish to share on my I2P Site" this should have the following changes:

1) Sites I host: Name change to possessive: "My I2P Sites Address Book" keep configuration file the same. UI Change to interstitial remove "Local Address Book" option from page.
2) Sites I added... wish to share: Name change to indicative "Known I2P Sites Address Book" keep configuration file the same. No UI change to interstitial.

Private Address Book: No change.

Router Address Book: Router address book gets most of the addresses it gets from subscriptions, therefore it is more self-explanatory to call it the "Subscriptions" address book. I also think it should be removed from the jump service interstitial options, although I totally understand if it's controversial to do so and will back off.

Published Address Book: No change to name required, although "Shared" was bandied about, it has some appeal. It would be nicer for folks if we could add a button which allowed for one-click publishing of the non-private address books to the published address book.

I also think that there might need to be another address book, to allow for the two observed uses of the Local address book can be accommodated adequately. If this were to be done, one of the roles from the 2 above would inherit the "Local" address book role, and one would be a new address book.

Mon, 25 Jan 2021, 07:28pm #3
zzz
Administrator
Zzz

did you find the glossary/style guide in mattermost from maybe mid-2019?

still haven't found anything on my local drives

Tue, 26 Jan 2021, 10:27pm #4
idk
I2P Legend

No I have not found the doc from last year yet. The last one I have is the one for the icons https://github.com/eyedeekay/Icon.Glossary.Styl... which is here. I'll keep looking.

Wed, 27 Jan 2021, 02:53pm #5
zzz
Administrator
Zzz

to clarify, the "proposal to make some changes to the addressbook for 0.9.50" is the bottom part of post #2 above? or those are proposed for this release, and the .50 changes are something else?

Wed, 27 Jan 2021, 03:07pm #6
zzz
Administrator
Zzz

streamr is not a general-purpose datagram tunnel. It's specific for streaming audio. Perhaps we could just hide it behind an advanced config. Or we need better docs.

Hidden Services: Here's the thread where I proposed using that name, both for historical context, for review of how we got here, and an example of how to foster community discussion before we rename things

Wizards: I too dislike the term, it's outdated and hackery-sounding. Need something better.

i2ptunnel help: decade-long issue, check trac. i2ptunnel is a mismash of tooltips and lack of docs. wizard isn't maintained as well as the regular flow, and probably isn't consistent. Renaming things doesn't solve all problems.

so you can't find any copy of the "style guide we started a year or two ago but which did not finish"?

I could swear that I went thru a couple years ago and changed "address book" to "addressbook" everywhere to make it consistent, which is why I was concerned about you going the other way without discussion. But I can't find it in the logs. Maybe it didn't happen.

Possessives: "My", "Our", "Your" are all problematic. There's probably at least one usage of each in our UI. It's all terribly awkward and should be avoided; let's not add more.

Wed, 27 Jan 2021, 03:29pm #7
zzz
Administrator
Zzz

I ran all our po files through a po spell checker https://github.com/holygeek/pospelchek to see what it turns up

a little wonky, looks like it strips "i2" off of "i2p" prefixes, but interesting anyway. These are the po files from the last release; we haven't regenerated them yet for .49

edit: I checked in fixes for a few of the obvious errors caught below.

pospelchek wrote:

# en_US word list, one per line, case insensitive
":
"{
({
\"{
\''{
above-listed
acceptor
acknowledgement
addressbook
addressbook's
addressbooks
addresshelper
allow_root=true
app_long_name
auto-detect
auto-detected
auto-start
auto-started
autofilled
autostart
barthélemy
bcc
bidir
bittorrent
blocklist.txt
bonaire
bouvet
bt
built-in
burkina
bw
caicos
cancelled
carrier-grade
case-sensitive
changelog
charset
cli
client-to-client
clients(dsa
command-line
config
configation
costa
cp
crit
curaçao
customised
d'ivoire
darussalam
dcc
decrypt
dest
dev
dht
dir
dist_os
dns
ds
ds-lite
dsa
dup
e.g
ecdsa
eepproxy
eepsite
eepsites
el
elgamal
err-clock
err-no
err-private
err-symmetricnat
err-udp
etags
faroe
faso
firewalled
floodfill
floodfills
frequently-used
front-ends
futuna
gc
guinea-bissau
hashcash
hexchat
hexchat-like
hh
higher-level
hostname
hostnames
hosts.txt
http
http_proxy
https
human-readable
identicon
iframes
igds
####
in-network
inproxies
inproxy
integ
introducer
introducers
ip
ips
ipv
irc
javascript
javastatus
jvm
kbps
kbytes
keyring
kitts
kosovo
leaseset
leasesets
leone
leste
localappdata
localhost
locally-generated
low-level
m-lab
m-lab's
maarten
macau
malvinas
marino
mayen
mayotte
miquelon
misconfigured
mistyped
mozilla,opera
multihoming
muwire
mynewserver.i
mysite.i
name:port
nats
netdb
network-synced
niue
non-embedded
non-existent
non-http
non-i
non-ssl
non-working
np.ntcp.maxconnections=nnn
np.udp.internalport=xxxx
np.udp.maxconnections=nnn
ntcp
occassionally
opentrackers
opererator
outproxies
outproxy
p'
p,proxy
p,server
p-dev
p-projekt.i
p_service_winnt.bat
paddresshelper
pagesize
palau
papua
pastebin
pcontrol
per-user
pid
ppp
prev
projekt.i
prouter
psk
psnark
psnark's
ptunnel
ptunnel.proxy.auth=basic
quantized
reachability
referer
referers
rekey
rekeying
reselect
retransmission
retransmit
retransmitted
rica
right-click
routable
router.config
router.maxparticipatingtunnels=nnn
routerconsole
routerconsole.advanced=true
rpc
run_as_user
réunion
sao
should_publish=true
sint
smtp
sri
ss
ssl
ssu
start-up
streamr
su
subdevice
subnet
subscription-based
susidns
susimail
sybils
symmetricnat
systray
tcp
theming
timespan
timor-leste
tokelau
trac
tradeoff
transifex
udp
ui
unban
unbanned
uninstall_i
unregister
unroutable
untrusted
uploader
uploaders
upnp
upnp-aware
upnp-compatible
uptime
uri
user-agent
user-agents
warn-firewalled
webapp
webapps
webconsole
webmail
webserver
well-integrated
wrapper.log
xpi
zipfile
}\
}\"
}\\'
Åland

Last edited: Wed, 27 Jan 2021, 04:05pm by zzz

Wed, 27 Jan 2021, 03:47pm #8
zzz
Administrator
Zzz

website (2300+) : http://stats.i2p/docs/www-pospelchek.txt

Fri, 29 Jan 2021, 10:51pm #9
idk
I2P Legend

I could swear that I went thru a couple years ago and changed "address book" to "addressbook" everywhere to make it consistent, which is why I was concerned about you going the other way without discussion. But I can't find it in the logs. Maybe it didn't happen.

That makes some sense, I only found 8 or 10 places where Address Book was spelled differently.

I'll take these and turn them into a new glossary/guide for review before I go any deeper.

Sun, 31 Jan 2021, 02:03pm #10
YesYesYes well maybe
I2P Legend

Renaming the wizard, so why not

guided configuration

guided performance configuration

auto-guided configuration

auto-guided performance configuration

Nothing ambiguous about those. The guided or auto-guided helps those that are new see that they will have some help and not be thrown into some sort of pit of options they know nothing about.

Other names

I and I bet most people when you say hidden service think of a hidden server you go to. So keep that meaning.

You need to make it perfectly clear what stuff is so why not.

encrypted communication tunnel
encrypted communication tunnel manager

another would be

encrypted routing tunnel
encrypted routing tunnel manager

It's very clear exactly what this is. I like the first better.

As for the internal personal router call it.

Personal Hidden service

maybe even more explicit

Personal Hidden service router

I mean this is about as clear as it can be and it's consistent in naming external hidden services and your own personal hidden service.

Mon, 01 Feb 2021, 03:11pm #11
zzz
Administrator
Zzz

"hostname" or "host name" ? I got both right next to each other on one of the console pages.

Seems like we want "host name" I think...

Mon, 01 Feb 2021, 06:27pm #12
idk
I2P Legend

Two words, host name would be most consistent with the previous rule. hostname fails the "spell-check test" as well. I bet that involves a lot of grepping, I'll take care of it if you don't feel like spending your time there.

Mon, 01 Feb 2021, 06:39pm #13
zzz
Administrator
Zzz

I'm going to change it in the couple places where I see it now but will leave the grepping to you after I'm done, thanks

Mon, 01 Feb 2021, 08:49pm #14
zzz
Administrator
Zzz

Done. Got a few places. Didn't mindlessly just global replace (and you can't anyway because "hostname" is a variable in the code all over). Sometimes changed to "address" or "host" depending on context.

Mon, 01 Feb 2021, 11:16pm #15
idk
I2P Legend

Per the brief discussion on IRC I will add hostname to the... list of surprising inadequacies in Mozilla Firefox's default English-language spell check dictionary and switch the term in the source code to `hostname` as opposed to `host name`. I will go through and read every one before I decide what word seems most self-evident. Sorry for the flip-flop, I'll make the changes tonight, don't worry about undoing anything.

Tue, 16 Feb 2021, 09:17pm #16
zzz
Administrator
Zzz

In the code review, I see you changed terminology throughout the code base in the comments. That's really not necessary and really bloats the review. When we talk about enforcing a consistent terminology, it should only apply to our UI and docs. Blasting a global-replace through the whole code base is really not helpful for anything.

Tue, 16 Feb 2021, 09:40pm #17
idk
I2P Legend

Ack, I'll minimize that going forward and only change docs where it's required to make a change clear.

Tue, 16 Feb 2021, 10:32pm #18
zzz
Administrator
Zzz

thanks. even found a place where you renamed a variable from 'hostname' to 'address'. Might have been right, but when the global replace starts touching code instead of comments I get nervous.

Thu, 04 Mar 2021, 01:29pm #19
zzz
Administrator
Zzz

While fixing some anchor links to the help page, I changed "Reachability" to "Network" in the sidebar, and "Reachability Help" to "Network Help" on the help page. See what you think.

Also, what do you think about changing "I2P Internals" to "Settings" in the sidebar? "I2P Internals" sounds scarier than it should be, and "Settings" is what most programs and apps call it these days. Or maybe "Configuration"?

Thu, 04 Mar 2021, 06:33pm #20
YesYesYes well maybe
I2P Legend

"Configuration" sounds best because it has graphs also.

Thu, 04 Mar 2021, 08:31pm #21
zzz
Administrator
Zzz

Not sure if there's a clean solution here.

The "I2P Internals" header links to configuration things. But the items under that header are a grab-bag, including graphs and other non-configuration things.

Fri, 05 Mar 2021, 02:40am #22
idk
I2P Legend

Network and Network Help are a little nicer, especially "Network Help" as a heading on the help page.

My vote would probably go to "Configuration" because it takes you directly to the bandwidth /config page by default, which places the whole menu of /config options at the top of the page for perusal. I went through all of them to double-check and everything under those tabs is for configuring something. The direct link to graph is on /home under "Network Information and Developer Information."

Sat, 06 Mar 2021, 04:46pm #23
zzz
Administrator
Zzz

All the /config pages have the title 'x configuration', and the section on /home is "Configuration and Help", so "Configuration" makes sense.

Speaking of /home, why the heck is it "Network Information and Developer Information" and not "Network and Developer Information" ?? Bugged me for quite a while but I don't think I ever mentioned it.

Back to the question in #21 above, does it make sense for the sidebar header to be "Configuration" with the current contents including several non-configuration pages?

Sat, 06 Mar 2021, 08:51pm #24
idk
I2P Legend

Speaking of /home, why the heck is it "Network Information and Developer Information" and not "Network and Developer Information" ?? Bugged me for quite a while but I don't think I ever mentioned it.

IIRC there was something of a debate between whether adding a new section to /home was a good idea when I was re-arranging the buttons, we settled on 4 sections(no new section) and that's just the string that was there when we froze the strings. Now that you've pointed it out, there's definitely a little awk there. I'll take it out.

Back to the question in #21 above, does it make sense for the sidebar header to be "Configuration" with the current contents including several non-configuration pages?

Let's see, so under I2P internals I have 3 items that lead to some kind of configuration if you count /graphs, /dns, and /i2ptunnelmgr, and another 6 that do not. But the I2P Internals heading links to /config... Maybe the answer is that this section isn't really a category at all in it's present state, it's just catching stuff we think people want to be able to access from the sidebar.

Then, if I go to "Advanced" there are no "config" items at all they all display advanced information. Same for "Help," but for troubleshooting information. "Advanced" is sort of by-definition a catch-all. Could have advanced configuration, but it doesn't. So maybe, some of the non-configuration stuff out of I2P Internals actually belongs there. By the same token, both "Help" and "I2P Internals" are default summaryBar members. Maybe "help" doesn't belong in "I2P Internals" anymore. That leaves: Logs NetDB Peers Profiles Tunnels. Logs could move to "Help" and the rest could move to "Advanced" and that would leave us with a section that could be accurately named "Configuration" and the remaining sections would remain accurate.

Sun, 07 Mar 2021, 12:21pm #25
zzz
Administrator
Zzz

"Advanced" section is not displayed by default, so best not to use that as an example, or move anything to it in an attempt to fix anything.

How about a new section "Diagnostics"? And we move "Setup" from "Help" to "Configuration"

Then we'd have:

Configuration
Addresbook Help Hidden Svcs Mgr Setup

Diagnostics
Graphs Logs NetDB Peers Profiles Tunnels

I'm still concerned that it's not obvious that you can click on the headers like "Configuration", so I'm wondering if we should also put a "Settings" link under "Configuraton" that goes to the same place.

Thu, 11 Mar 2021, 07:30pm #26
idk
I2P Legend

That set of categories makes the most sense of what we've talked about so far, and I like that. Diagnostic section sounds like a good plan.

It might not be obvious enough, and I think I'd rather be redundant in a not-very-noticable way than not obvious enough. OTOH, any of those options will take you to a page where all the other config pages are exposed in an obvious way, so maybe it doesn't matter that much? That's the argument I have with myself over it right now. I think I lean toward the position that "Settings" inside of the configuration settings is better.

Fri, 12 Mar 2021, 02:38pm #27
zzz
Administrator
Zzz

like this?

Configuration
Addresbook Help Hidden-Svcs-Mgr Settings Setup

Diagnostics
Graphs Logs NetDB Peers Profiles Tunnels

Sun, 14 Mar 2021, 04:34pm #28
idk
I2P Legend

Affirmative, that is what I think makes the most sense. If we're agreed I'll do the implementation of the Diagnostics section in the sidebar.

Sun, 14 Mar 2021, 06:21pm #29
ReturningNovice
I2P Legend
Sitelogo

I like the changes proposed in #27

To me, even though I am used to the status quo, these changes make sense and seem like they should be more intuitive for new users.

Mon, 15 Mar 2021, 11:17am #30
zzz
Administrator
Zzz

ack