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.
-
You have a long sentence with multiple elements. You might just want to make a bullet pointed list.
-
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
- 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.
- 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.
- 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 Magic number (programming) - Wikipedia
(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: Colon | The Punctuation Guide
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.
-
private key doesn’t need a hyphen
-
« identifier-password pair » might be a better phrase
-
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
Eavesdropping - definition of eavesdropping by The Free Dictionary
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
https://p.teknik.io/F4xqb
https://p.teknik.io/l53Qi
https://p.teknik.io/fOD3K
https://p.teknik.io/qnh5G