This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- ARK Ecosystem
- Technical writer:
- yslcrypto
- Project name:
- Project 1 - Getting Started With Core Blockchain Development Guide
- Project length:
- Standard length (3 months)
Project description
Here are some thoughts after reading through the Getting Started section:
HOW TO SETUP YOUR DEV ENVIRONMENT
Installation: I would go deeper into how to install the development tools here. I’d provide code samples, along with common errors and how to fix them (we could link to a troubleshooting page here).
Spinning up your first testnet: First impression: right now it’s pretty confusing for someone who’s just skimming and wants to get setup quickly. Here are some things I’d change:
I’d consider defining even basic concepts like testnet.
I’d provide more shorter code samples: mkdir, cd, etc. I’d also group them together so readers can copy and paste more easily. Nothing is too simple, and everyone loves to copy and paste.
On first reading, it’s unclear to me what steps 1 and 2 of the network boot subsection achieve. Clicking and going through the links takes too much thought. I think we can make this much clearer without getting too far into the weeds.
I’d at least give a high-level overview of core-container in step 5 (which I think is really step 4?) so the reader has some intuition for what they are doing without following a link.
For steps 3 and 5 (really 4), I’d explain the longer code samples.
For the final step, I’d link to the installed plugin and file to make life easier for the reader.
Finally I’d edit in a way that ensures there is no more than one idea per paragraph (allows for easy skimming). I’d also make the tone a little more fun / friendly, and add a couple of emojis.
HOW TO MONITOR THE BLOCKCHAIN
I’d simplify the first paragraph. I’d explain what a plugin is, what a delegate does (or at the very least link to a first-principles explanation), what forging a block means, and give an example of a network event.
Define the problem: I’d give the reader an intuition for what a full node is, link to a more detailed explanation, and better explain the tradeoffs between a full node and an external application. Finally I’d link to the previous getting started page -- how to setup a working testnet and development environment -- at the end of this subsection (in case the reader has stumbled across this page first).
The Events API: It’s not clear -- from the list of available events -- that we should use ‘block.applied’ to get what we want. Although the Tip below makes it clearer, I would explain this before.
It’s not clear to me what ‘block.applied’ returns. I think it’s important to make this crystal clear.
In the code example at the end, I think it would help to make it clear that ‘block.generatorPublicKey’ replaces ‘block.forger’ (in the previous pseudocode example), and that ‘delegateKey’ replaces ‘delegateWeAreMonitoring’. Finally, to ensure the code and pseudocode samples are consistent, I’d also swap ‘delegateKey’ and ‘generatorKey’ in the if statement.
Creating the plugin: I’d explain what scaffolding means in this context. Something like: Just like real scaffolding in a construction site, when we talk about scaffolding in this context, we mean a simple prebuilt structure for your plugin, on top of which you can build the real one.
I’d add code samples to rename the directory and plugin, show an example of package.json, and explain what we mean by ‘adding the necessary configuration’ to plugin.js.
Tying it together: I’d make it clearer what the changes are. And finish with a congratulatory ending and some more emojis :)
HOW TO SEND YOUR FIRST TRANSACTION USING ARK SDK
Getting Started: I’d add a code sample to allow the user to create a new directory with copy-paste.
Connect to Testnet: I’d explain what a REST API is, in case the reader is unfamiliar (or at the very least link to an explanation). I’d give and link to an example of a JSON Viewer. I’d use a friendlier tone in the second TIP (since we are asking the reader for a favour).
Changing Config Manager: I’d mention common examples of network-related bugs, and consider linking to a troubleshooting section.
Setup Sending and Receiving Accounts: I’d add a code sample to allow the reader to change to the config directory with copy paste. I’d add a code sample showing the contents of delegates.json.
HOW TO SEND TRANSACTIONS USING THE ARK CORE TESTER CLI
Prerequisites: I’d add a code sample that shows how to get a working copy of the ARK Core GitHub repo, and another that moves the reader into the right directory.
Basics: I’d make the first paragraph clearer for those who aren’t familiar with path environment variables.
CONCLUSION
To conclude, these are just some brief notes I took while reading through the documentation. When we start on the project together, I'd want to go through the process myself to see where I trip up. And use that knowledge to further simplify the docs.
Finally, while I've only gone through one project here, I don't see this taking more than a couple of weeks. As discussed in our email correspondence, I think it would be possible to work on several projects during our time together.