Appel aux Geeks Anglophones: révision du matériel pédagogique

Thank you for biting my french click-bait… I will not further insult your eyes or the french language.

I NEED YOUR HELP
…in reviewing a git repository that documents what I’ve learned since discovering LibreMoney on May 9th 2020. I’ve set a goal for myself to have something useful for english-speaking geeks by mid-January 2021, so I’m asking for others to review my work with hopes that I’ll have obvious errors corrected well before then; also, I foresee a few distractions in my immediate future (finding a new place to live, and preparing myself to achieve my New Year’s Resolution: converting from only-learning to also-contributing).

WHERE TO GO:
My repository can be found at https://git.duniter.org/spencer/learn-g1/-/blob/master/index.rst which is a brief splash-page welcoming the visitor and offering a single call-to-action hop right in link to bring them into the Table of Contents within /docs.

WHO IS THIS FOR?
The target audience is technically-curious english speakers. A young student, or even grandma and grandpa, who are interested in learning python-code and basic concepts of blockchain might spend from 2-3 days to 2-3 weeks working through the docs and accompanying code examples. An experienced pythonista familiar with blockchain might spend a few hours then hit the ground running, having quickly learnt all that I have labored through in the past 7 months.

WHAT YOU WILL FIND
The repository has simple python code examples that are meant to illustrate basic concepts useful in understanding the LibreMoney project. Where documentation exists, the Title links directly to its corresponding code file(s). Documentation is meant to be minimal, with useful and accurate examples of code output which was run against the production g1 blockchain. Code is meant to be easily-understood, without jumping through many libraries… useful as a reference, admittedly useless as production-quality.

MUCH IS MISSING
…because I still have plenty to learn; I hope to maintain and grow this repository along the way; I dont even yet know all that I don’t know.

Off the top of my head:

  • I need to expand the Getting Started: blockchain_basics.rst document.
  • All docs need a « See Also: » section with links to existing english documentation.
  • jsonize_wot.py is a flimsy hack, that has been useful for me to learn and inspect the WoT, when the monit.g1… site gives errors, but many other tools exist that make learning the WoT easy without my crazy code. Not sure how useful this is for others… it is what it is.
  • if it turns out that this content might be useful to native francophones, then code would need internationalization (I’d happily do that) and localization (I’d need help with translations), and /docs would need to be split-up into /docs/en and /docs/fr.

WHY HERE INSTEAD OF THE TECHNICAL FORUMS?
The developers have been kind with their time, have taken me under-their-wing, as so many of you have, and were an encouraging force in their review of my first document last month… before I continued on with the rest of the documentation that is available today. Now I need more eyes, including less-technically-advanced eyes, to offer peer review so that I know if what I’ve been working on is truly useful for learning about LibreMoney. I would REALLY appreciate your feedback, and I hope that at least some of you find this useful.

Thank you all so much for your time. Joyeuses fêtes pour la fin d’année! <3

Respectfully,
Spencer971

7 J'aimes

Aussi: publié comme « demande » sur gchange:
Total de 500g1 à distribuer pour les contributions de révision jusqu’au samedi 9 janvier, 2021.

[ajouté le 9 janvier 2021]
Ce matin, j’ai cloturé cette publicité sur gchange, et j’ai l’intention de payer 100% de 500 G1 plus le reste de mon solde ce soir a Scuti (un paiment de 865G1 en total) qui a depassé, fortement, mes expectations originals.

Bravo Scuti, et merci!
Spencer971

Documenting is contributing! I will need some time and calm to provide a review, but from what I can see, this example-based approach could illustrate well the whitepaper.

1 J'aime

I can help. Do you just need feedback and reviews, or would you like commits to your repository? How formal is your writing meant to be?

3 J'aimes

not so formal… approachable and useful by many is the intent. Feedback is wanted where it can improve the docs… merge-requests would be icing on the cake… but maybe better to discuss big changes here if this thread actively changes.

added Dec 24, 2020: Scuti, I love all of your feedback, you’re doing great work and I agree that « more formal » will improve the documentation considerably. I will not interject to break up the post that you keep adding to… but please know that Im watching and appreciating all of your feedback… which will make it into the repo for sure (and into my head, hopefully). -Spencer971

[added: dec 25] Another day, and I wake up to many more improvements. Scuti… you are a master of the english language, thank you so much; and Merry Christmas to you and yours! -Spencer971

[added: dec 27] Your review is better than I ever received 35 years ago in english class. While you’re improving the documentation, you’re also improving my future writing. ty again scuti! -spencer

[added: dec 29] Another day, and more improvements (and detailed hard-work) on your part. As for signatures… any software that signs a message on your behalf can only do so with your private key. There are naughty softwares which keep your private key in memory (where it can be leaked) and these might NOT ask when creating a sig because they dont need to… or they may ask if they’re trying to warn you before they create the signature (even though they dont need to since they already have your keys). Other, better behaved softwares will NOT store your private key in memory for longer than they need it… and would be forced to ask you to provide your credentials or private key whenever they need to do something like sign a message or decrypt something meant only for you (or encrypt something in the manner that cesium+ messaging works… where the encryption is done with sender’s private and receivers public).

[added: jan 4] More work done, seen and appreciated. Scuti, you’ve gone so far above and beyond the call that every G1 available to me will be transferred mostly (if not all) to you at midnight on Jan 9. Currently, Im expecting that to be around 700G1 (because I intend to pay 10du to g1formation on the 8th) but I will still feel like I owe you more, and will make it up to you one way or another.

[added: jan 5] Whichever method is easiest for you Scuti, I will appreciate how it’s delivered. Thank you.

[added: jan 6] I see that you’re into the documentation for scripts. Please know that Im reading daily, and going back to review your previous notes. The pastebin style notes will work out well; I’ll be reading your notes alongside my documentation as I apply changes. You keep bumping into many of my bad habits, so please know that where you’ve already corrected me previously, Ill bring improved habits and apply them down the line; you can, but don’t need to, repeat corrections if it would be easier to just say « see previous corrections ». Thanks again Scuti.

[added jan 9] I see your additions for unsigned_transaction. The sum of inputs must equal the sum of outputs, so I think it’s safe, and better, to say that client software must include a change output whenever the intended payment(s), as outputs, sum to less than the inputs. (in other blockchains, this is not the case… any value not included in outputs becomes miner fees… as long as they include that value in their coinbase).

I’m going to assume some level of formality since there’s a difference in expectation between conversational English or blogs and documentation or courses. I don’t know if it’s different in France, but concise writing is generally favored over verbosity.

For example:

This repository is intended for those who wish to learn how G1 LibreMoney works under the hood.

This sentence is okay. When you camel case LibreMoney like this, people will assume it’s a brand or trademark, which I haven’t seen G1 portrayed this way in other pages. If you mean to convey monnaie-libre (free-as-in-freedom money), libre is an acceptable loan word .

It is helpful, but not necessary, to have basic understanding of blockchains and python code; your geeky curiosity is enough to fit the target audience.

It is helpful but unnecessary to have a basic understanding of blockchains and Python. Your geeky curiosity is enough.

Code here is written with a preference for ease-of-reading without jumping through libraries; it’s meant for introductory learning purposes, NOT for production.

Code samples in this repository are easy-to-read and independent of libraries. However, it is meant to teach and is not for production.

Replaced « here » with « in this repository » for less ambiguity (here may imply specific page only).

This minimalist documentation is meant to express my strong preference for RTFCode over RTFM.

It’s unusual for git repositories to use personal pronouns or reference. To convey the same information, it would be more like:

This repository favors minimalist documentation and RTFCode over RTFM.

Edit: Double check minimalist vs minimal


I would go with « minimal ».

Edit2:

https://git.duniter.org/spencer/learn-g1/-/blob/master/index.rst

General feedback on the whole document:

Unless you’re quoting someone, contractions are generally absent in technical, academic, or business writing. By using them, you may accidentally open yourself to grammatical errors since some phrases sound or occur naturally but are grammatically incorrect. Whether you want to leave it in is up to you. This document reads personal and informal.

Let’s head-out on a journey towards technical-understanding of how the G1 LibreMoney blockchain works.

Either:

Let’s make a journey and learn how the G1 blockchain works.

Head out on a journey and learn …

Admittedly, « Let’s head out on a journey » isn’t wrong and you may hear it in casual conversation. The case is different for writing under scrutiny.

Along the road, we’ll re-invent the wheel a few times.

Along the way …

I would change « road » to « way » since the latter is more abstract.

Will our wheels be any lighter, stronger, or better balanced than others? It’s not the point.

These sentences are okay.

We’re studying something interesting and useful, and to confirm it, we’ll implement what has been learned.

This sentence is okay. Someone else may recommend you start another sentence as opposed to "and " since you already have a transitional phrase (« to confirm it »).

I intend to continuously challenge myself, being prepared to share and effectively guide other coders – and future coders, along the way.

… effectively guide other coders and future coders along the way.

Dashes are versatile, but unnecessary in this sentence.

For better word variation since my earlier recomendation included « along the way », you may want « as I go ». But I would just prune it and the adverb « continuously » because what you’re doing is already communicated without those words.

I’ll also be studying existing tools and libraries in the G1 community.

Okay.

Having re-invented wheels, we can better appreciate the projects of fellow developers.

Okay.

We’ll work towards the longer-term goal: to offer measurable value by contributing to new and existing community projects, building on the shoulders of giants, from a solid foundation and with fresh perspective.

Okay.

So. What do you say? Join me and hop right in!

So what do you say?

Punctuation for « so » can be strange, but in this case, it shouldn’t be it’s own sentence.

Your participation, help and feedback is much appreciated.

Add comma after help.

Append:

https://git.duniter.org/spencer/learn-g1/-/blob/master/docs/requirements.rst

The name and description of this document would be easier understood if it was titled ‹ setup ›. Requirements can imply what is needed to set up as opposed to the set up process.

For those who are just reading the contents of this repository, none of the following will be necessary.

I would prune this sentence even though I get what you’re saying (« if you just want to read, but don’t plan on coding »). Not from an English language arts perspective, but a general writing one. With the way you phrased this, you can confuse people who are currently reading at the moment, not specifically the ones who don’t plan on coding.

However, if you will be tinkering with code and/or running the code on your machine (be careful – this is not production quality code), then this document may be helpful in preparing your computing environment.

This sentence is grammatically fine, but it’s wordy. (You mentioned earlier you prefer minimal documentation and RTFCode, but thus far documentation is verbose.) For example, the reader can already infer the purpose of the document by the title and table of contents, so this paragraph comes across as redundant information.

If you want to warn people about the code, you can get straight to the point by disclosing the risks.

Cesium is available for Iphone, Android, desktops, and via extensions for Brave, Firefox and Chrome browsers. The browser extensions work great, allow to save your keys as an encrypted ewif on your computer, and can serve as a convenient blockchain explorer while digging-in. Search-for and install Cesium within the extension-settings of your favorite browser.

Abstractly, just provide a link. Don’t rely on a search engine to direct people to the software you’re talking about. For example, it already conflicts with the name of a real life element, but it also conflicts with other projects with a greater presence in the English-speaking world.

You also don’t have to give a small review of the wallet extension. If your guide is written around using Cesium, trying to convince people to use Cesium is out-of-place.

Cesium is available for Iphone, Android, desktops, and via extensions for Brave, Firefox and Chrome browsers.

I would change ‹ via › to ‹ as › and remove ‹ browsers ›. Those web browsers are recognized brands (maybe not Brave), but readers will be able to infer what it is.

The browser extensions work great,

Added note and self-correction: When you’re talking about software (or browser extensions), it’s often considered singular. So when you say Cesium, it’s thought of as a single browser extension that is available on multiple platforms. « Browser extensions » is more often going to be associated with multiple, different extensions (NoScript, uMatrix, and so on).

The browser extension
… works great

allow to save your keys as an encrypted ewif on your computer,

… saves. Remove ‹ allow ›.

and can serve as a convenient blockchain explorer while digging-in.

… serves as a

Remove « while digging in ». It’s extraneous and a phrase that makes more sense in a conversation than it does in writing.

I would just skip fluffing Cesium and remove the entire sentence.

All scripts contained here are written in Python version 3. This learn-g1 repo is a git repository. Some external python packages are required and can be installed via the pip3 package manager. If you don’t already have these installed, you’ll need « Administrator » access to install them on your computer.

The following examples will install « python3 », « git », and « pip3 » onto your local machine.

I know you’re trying to handhold absolute beginners, but you have to understand the different levels people are at. Any beginner who is not using APT as a package manager must go off track and use equivalent commands to set up Python, git, and pip. Doing so requires much more understanding than the level you are trying to target. So it makes a lot less sense to try and introduce Python, git, pip, and how to use an operating system in this document. You also start bulking the document with irrelevant information for the people you can reasonably target.

All scripts contained here are written in Python version 3. This learn-g1 repo is a git repository.

This git repository contains Python 3 scripts. (This revision also changes passive voice to active voice.)

Some external python packages are required and can be installed via the pip3 package manager.

Either move this sentence to the next section or cut it out entirely.

If you don’t already have these installed, you’ll need « Administrator » access to install them on your computer.

This sentence is fine grammatically, but it’s silly to try and instruct people on how to use their operating system.

Effort was made to avoid requiring many external dependencies – so that learning about G1 LibreMoney could be done without also learning many other 3rd-party libraries; however, a few external python packages are required by the scripts in this repository.

Remove the dash. Generally, if you’re going to use ‹ so › pay attention to punctuation.

The car was at the mechanic’s, so it got fixed. (conj. #2)

He went to the mechanic so his car could get fixed. (conj. #3)

Recommendation: This repository minimizes the use of external dependencies; however, a few packages are still required.

This also switches pssive voice to active voice.

Some scripts will require a connection to an available duniter node.

This sentence is okay, but you can do without ‹ will › and just say the ‹ scripts require ›. You may want to capitalize Duniter.

To make this easy, set and export your DUNITER_BMA environment variable to a value that matches the format: « method://hostname-or-ip:bma-port » or do so in your ~/.bashrc file.

This sentence is okay. You could do without « to make this easy » for a more concise writing style.

For Cesium users, you can find a list of duniter nodes by going into « Settings ». Under « Network » click « Duniter peer address » then « PEER’S LIST ».

More concise: Cesium users can find a list in Settings. Under Network, click Duniter Peer Address then PEER’S LIST.

Scripts that create DUBP documents will default to Currency=g1-test for the test network.

Recommend: Scripts that create DUBP documents default to Currency=g1-test, the test network.

You can do without ‹ will default › and simply write ‹ scripts default to ›. You may want to introduce what DUBP stands for.

This can be changed, via your DUNITER_CURRENCY environment varaible, to ‹ g1 › for the production network… but if you do so, be careful!

This can be changed via your the environment variable DUNITER_CURENCY to ‹ g1 › for the production network, but be careful.

Rearranged to introduce the environment variable first, then specify it. Changed commas to (independent clause), (conjunction) (independent clause).

The following example will clone this repository, creating a ‹ learn-g1 › folder under your current working directory, and leaving you inside the directory of your own local copy.

The following example will clone this repository, create a ‹ learn-g1 › folder, and change the current directory to it.

My general feedback: when you have headers, you don’t need to add the ‹ : › after the word.

Following are my thoughts on useful concepts – building blocks that we might strive to understand, in order to benefit every-day utility from available open source software based on cryptography.

This sentence is too personal (also broken). If you ramble like this, you might make the reader guarded in having to filter useful information and opinion. You shouldn’t be portraying opinions in technical and instructional documents either.

If it is truly useful, write with confidence. Write about the subject, not yourself.

Also ‹ everyday › does not need hypens.

Cryptography:
It’s about securing free-speech and expression in our electronic lives… whether that be: keeping our own thoughts private until we are ready to share them; having confidence and capability to associate, communicate, and contract voluntarily with select others; to prove that we know information without having to share details until later if-necessary, and more.

  1. You have a long sentence with multiple elements. You might just want to make a bullet pointed list.

  2. Replace the ellipsis with commas. (Ellipsis indicate omission. You wouldn’t want it on instructional or technical documents.)

whether that be: keeping our

whether that is keeping our

  1. I don’t know if you intentionally expanded words into whole phrases for accessibility. In order, I believe what you’re describing (in an extremely verbose manner) is security, confidentiality, and privacy. When you have this many words for simple concepts, your readers will have to figure out what you’re talking about as opposed to having your ideas communicated immediately.

I recommend:

Cryptography is about securing free speech and expression in the digital world through security, confidentiality, and privacy.

I picked ‹ digital world › over our ‹ electronic lives › to skip the personal pronoun. Also, ‹ free speech › does not need hyphenation.

Cryptography is an evolving science that can offer us high confidence of security, in limited aspects, in our everyday electronic lives… but it is NOT perfect, 100% security does not exist, and that which is secure today may not always be secure in the future as computation technologies evolve and mathematical discoveries are made.

This is a big run-on sentence.

Recommend: Cryptography is an evolving field that offers security to an extent; however, perfect security does not exist. What is secure today may not be secure in the future as technology evolves and mathematical discoveries are made.

in limited aspects
but it is NOT perfect, 100% security does not exist

The ideas communicated with these segments is combined into one.

It is helpful to understand what is being secured, and the role we must play, in order to have realistic expectations.

Re-arrange to:

In order to have realistic expectations, we should understand what is being secured and the role we must play.

Parenthetical comma before ‹ and › may mislead people into thinking you are starting an independent clause. This also places the transition phrase to the start of the sentence.

One-way Function (aka: trap-door, asymmetric relationship):
It’s the magic basis of cryptography, the fact that some things can be done yet cannot be undone is exploited mathematically and computationally throughout cryptography.

Run-on sentnece.

It’s the magic basis of cryptography.
The fact that some things can be done yet cannot be undone is exploited mathematically and computationally throughout cryptography.

  1. In formal writing and certain editing styles, when you have a word as a header, you should still use the word as opposed to « it » or a pronoun to start the sentence of your paragraph.

One-way functions are the basis of cryptography.

  1. I think there’s a better word than « magic basis ». I understand you’re trying to convey that one-way functions are a crucial aspect of cryptography, but the word basis is implying it is foundational (maybe that is what you’re trying to get across). You might also conflict with the mathematical defintion of basis.

« Magic » in programming contexts is also associated with https://en.wikipedia.org/wiki/Magic_number_(programming)

(The connotation isn’t good.)

Often called one-way functions, or trap-door functions, or asymmetric relationships, they refer to being able to easily produce a specific output from a specific input, without feasably being able to reproduce the same input having only the output.
Often called one-way functions, or trap-door functions, or asymmetric relationships, they

You already introduced the terminology and its aliases in the header.

Recommend:

#1 One-way functions produce a specific output from a specific input without feasibly reproducing the same input having only the output.

(Closer to the original)

#2 One-way functions produce a specific output from a specific input; however, the input cannot be feasibly reproduced having only the output.

(Does not indicate a one-way function reproduces an input)

We might think of a camera as a one-way function, we can easily take a photo of nature, share it with others and everyone knows that it is a picture of nature… but we cannot feasibly recreate the same nature having only the photo.

You have another run-on sentence.

We can think of a camera as a one-way function.

We can take a photo of nature and share it with others. Everyone will know it is a picture of nature, but we cannot feasibly recreate nature having only the photo.

If you want your writing to be easy to read, you should start new sentences when you can.

Private Key (aka: Seed, Secret Credentials):
It’s a secret that ONLY we will ever know and we must ALWAYS be able to recall it.

Revise to exclude « we ». The sentence currently means it’s a single secret that we both know.

Assuming nobody else has access to this: each can trust that they are the only ones capable to speak or act, contractually, electronically, on their behalf.

You’re trying to say something like, « if no one has access to someone else’s private keys… » but your sentence pertains to a specific instance (« this ») as opposed to generally speaking.

The private-key is just a number, but it can be represented as: a list of seed words, a secret-identifier and password, a precise string of seemingly random characters, and even as a QR-Code.

A private key is just a number,

The colon after « represented as » should be changed toa comma.

Refer to: https://www.thepunctuationguide.com/colon.html

Whichever manner the private-key, or seed, or secret-id/password, is represented by the chosen software… it is crucial that ONLY we will ever know it and that we will ALWAYS be able to recall it.

  1. private key doesn’t need a hyphen

  2. « identifier-password pair » might be a better phrase

  3. You are using « it » to refer to two different things within one clause:

it is crucial that ONLY we will ever know it and that we will ALWAYS be able to recall it

Make it strong, make multiple back-ups, then store them dispersed and secure.

This sentence is okay though it sounds foreign.

Public Key (aka: Address):
Think of it as a public-facing identity, that only we control, when interacting with others in our electronic lives.

Recommend: The public key is like a public-facing identity. It is only controlled by the bearer of the private key.

It is just a number (representing a coordinate) which was created by our private-key.

It is a number, representing a coordinate, created by the private key.

(This avoids passive voice.)

The public-key is shared with others in order for them to verifiably identify us when we are communicating and making agreements with them.

The public key is shared in order for others to verify identities in communications or transactions.

A public-key, or address, is represented as a precise string of seemingly random characters, and normally shared via QR-code.

A public key or address is represented as a string of nonmnemonic characters and is normally shared via QR code.

Relationship between Private and Public keys:
The private-key is used in a one-way function to create the public-key… having only the public-key we cannot feasibly learn the private-key. We guard our private-key as secret, we share our public-key with others in public.

You may want to merge this section with the previous since you introduced both private keys and public keys at this point.

having only the public-key we cannot feasibly learn the private-key.

Here, you re-iterate one of the concepts from the previous section.

Recommend:

The relationship between private and public keys is that a one-way function creates the public key from a private key. As the names suggests, the private key is kept secret while the public key can be shared.

Information (aka: Message, Data):
Exactly what you think it is.

Don’t assume what the reader is thinking. People can strangely interpret simple words if they’re in a new context.

Try:

Information, message, or data are as the words suggest.

In our electronic world, everything is information.

This sentence is okay, but you may want to replace « our electronic world » with « the digital world ».

Whatever we say or do, electronically, requires and results in information.

This sentence is okay, but you may want the word « digitally » instead of « electronically ».

Information is quantitative and qualitative, it has a size and specific value.
This sentence is okay.

Hash:
A hash is a highly compact form of information to precisely identify and/or represent any other information (regardless of type, complexity or amount).

This sentence is okay. The adverb use is questionable. For example, if the reader does not have a point of reference of what is simply compact and what is highly compact, the word serves little purpose. So you might want to remove « highly ».

Its specialty is that it’s a small identifier that can ONLY be created by its original information;

Decapitalize « ONLY ». Add comma after « however ».

however knowing only the hash we cannot learn any of the original.

(; ) however, knowing only the hash, we can not reproduce the (original|hashed) information.

It can be used as a commitment, a declaration to others that we know something specific without sharing any details now, and later be able to prove that we knew them all along.

Disambiguate the pronoun « it ».

A hash can be used as a commitment, a declaration, or proof of knowledge without sharing the details.

A hash is just a number, it can be represented as a precise string of seemingly random characters, shared via QR-code, but is most often burried in software so that we don’t have to deal with it.

A hash is a number. (Start new sentence.)

It can be represented as a nonmnemonic string of characters and shared via QR code, but it is often buried in software, so we don’t have to deal with it.

(closer to original)

It can be represented as a nonmnemonic string of characters and shared via QR code, but it is often used by software rather than the end user.

(eliminate « we »)

Relationship between Information and its Hash:
The result of passing information through a one-way hashing function is the information’s hash… having only the hash we cannot feasibly learn anything about the original information… neither its size, nor its value.

You can merge this section back as a paragraph.

Recommend: Information passes through a one-way hashing function to create a hash. Having only the hash, information, its size, and its value cannot be recreated

In the instances you use « recreated », consider if you want to use the word « ascertain » instead.
https://www.thefreedictionary.com/ascertain
1. To discover with certainty, as through examination or experimentation.

Signature:
Very much what you think it is, except even more precise and verifiable.

Similar feedback about not assuming what the reader is thinking.

A signature is much like it’s (conventional|traditional) counterpart; however a cryptographic signature is more precise and verifiable.

In cryptography, we pass our private-key and a message to a one-way signing function which results in a signature… a short message that others can use with our public-key and a copy of the information (often a hash of other information) to verify that we indeed signed exactly that information… that it wasn’t anyone else that signed it, and that the information hasn’t changed since it was signed.

Break this sentence up.

A private key and a message is passed to a one-way signing function to create a signature.

(closer to original, skip personal pronoun)

A one-way signing function creates a signature from a private key and information.

(avoids passive voice, uses information as opposed to message because information has a section title.)

A signature is a short message used with a public key and a copy of the information to verify the signer and the integrity of information. The information used in signatures is a often hash of other data.

A signature is often appended to the bottom of a document, can be represented as a seemingly random string of characters or QR-code, and is normally buried in software so that we don’t have to deal with it.

seemingly random string = nonmnemonic string

buried in software so that we don’t have to deal with it = utilized by software rather than the end user

This sentence is okay. The above phrases make it look wordy.

We get hints from software whenever a signature is being created, because we’re doing something special and the software needs access to our private-key.

I don’t know what you mean, and the word « hint » is throwing off my interpretation. Do you mean cryptographic software notifies the user whenever a signature is created? (I don’t encounter this regularly, so I can’t relate.)

whenever a signature is being created

This means the software hints whenever it is in the process of creating (as opposed to after the signature is created). (From my experience, creating a signature is generally instant.)

RE:

We get hints from software whenever a signature is being created, because we’re doing something special and the software needs access to our private-key.

I would re-use this sentence for your document:

Any software that signs a message can only do so with a private key.

You need the extra context that the private key is sensitive information and using it is similarly a sensitive operation. It’s not a good idea to comment on the UX (user experience) of software in the context of cryptography or mathematics.

Relationship between Signer, Information, Signature, and the public.
Only the owner of a private-key can sign information to create a signature. Anyone in public who knows the information and public-key of the signer can verify the signature, verifying specifically who signed what.

Similar comment. Merge back with the previous section.

CipherText (aka: encrypted message):
It’s a form of information that has been scrambled through a one-way encryption function by the sender to prevent eves-dropping by all except its intended recipient.

As previously commented, change « it’s » to « CipherText ».

to prevent eves-dropping by all except its intended recipient.
Change eves-dropping to eavesdropping
https://www.thefreedictionary.com/eavesdropping
You can remove « by all except its intended recipient ». It doesn’t make sense for your intended recipient to eavesdrop.

There are a number of methods for doing this, with different trade-offs, but they are normally buried in software so that we don’t have to deal with ciphertext. When visible,

Same comment with « buried in software ».

ciphertext appears as a seemingly random stream of characters which informs us nothing qualitative about the original, however its size is relative so we can learn something about the size of the original information.

Cipher text is a nonmnemonc random (stream|string) of characters that does not have qualitative information about the original message except its size. (So|this|therefore), the size of the original message can be inferred.
seemingly random = nonmnemonic

Our software may or may not require our private-key when sending an encrypted message; in the prior case we’re literally or effectively also signing the message. Our software will require our private-key whenever decrypting an encrypted message, since it’s meant only for us.

Same comment with software There are too many variants for it to be a good idea to comment on the UX.

Cryptographic Protocols:
Whenever the above (and more) building blocks of cryptography are combined in a specific manner, whether it be interactive or non-interactive between participants, we call it a protocol.

This sentence should be re-worked. You can reference the definition of protocol.

I think I understand what you mean but interaction is the right word you’re looking for.

When you make a section, you should start the paragraph with the subject.

A cryptographic protocol combines aforementioned concepts…

There are numerous cryptographic protocols, each with specific use-cases and trade-offs;

these protocols are a challenging subject of continuous engineering design and constant evolution, and can offer considerable utility in our electronic lives (when not misused).

Remove « these »:

Protocols are a challenging subject of continuous engineering design and constantly evolution…

continuous engineering design

I think I understand what you mean, but your nominalizations are making your sentence harder to read than it should be. For example, removing it and slightly changing the sentence makes it more clear.

Protocols are constantly evolving and can offer considerable utility in your digital world when not misused.

Some are easy to accomplish for the end users, others are lengthy and involved, the best ones are well buried in software so we never have to deal with them.

Run-on sentence.

Some are easy to accomplish for the end users
I think you mean:
Some are accessible to end users. Others (aren’t. | are more complex).

Same comments on « buried in software ».


Update

It’s becoming harder than it should be to review your work in a giant forum post. I put my feedback in a file for





2 J'aimes