wallet-transfer-queendolineakpan: submission for multi-currency wallet transfer documentation#17
Conversation
|
Looks good @TechSis01! Thank you! 🎊 |
submissions/Multi-currency_wallet_transfer - Queendoline_Akpan/tutorial.md
Outdated
Show resolved
Hide resolved
OfficialJhimmy
left a comment
There was a problem hiding this comment.
Hi @TechSis01 , thank you for putting this together! I can see the effort you put into structuring the setup guide, and it’s a solid starting point. You’ve clearly highlighted prerequisites, authentication, and environment setup, which are essential parts of a technical tutorial. That said, I think there’s a lot of room to improve clarity, flow, and completeness so readers can really follow along without confusion. Here are my suggestions:
-
Structure and Flow
• The numbering of sections feels inconsistent (for example, “## 2. Get Your Chimoney API Key” right after prerequisites, but the previous section isn’t labeled “1”). Keeping the numbering consistent makes it easier for readers to follow the steps.
• The tutorial ends rather abruptly by pointing readers to another file. Instead, you could include at least one short example (like creating a wallet or making a simple transfer) within this guide. That way, it feels more complete on its own. -
Clarity and Explanation
• Some steps are too brief. For example, in the Node.js setup, you only mention installing Axios but don’t explain why Axios is being used or what role it plays. A beginner might just copy-paste without understanding.
• In the authentication section, it would help to explain what headers are and why they’re important, especially for someone new to APIs. -
Grammar and Wording
• Watch out for small grammar issues and wording choices. For example:
• “An IDE most preferably VSCode” → “An IDE, preferably VSCode.”
• “Your API Key needs to be included in the headers of your API requests for successful authentication.” → This could be simplified to “You need to include your API Key in the request headers so the API can authenticate your calls.”
• Keeping sentences short and direct makes technical writing much easier to digest. -
Writing Best Practices
• Avoid linking directly to another submission file inside the tutorial (/submissions/...). For public readers, that link won’t work. Instead, summarize or embed the key parts in your own guide.
• Be consistent with capitalization. For example, you sometimes write “API Key” and sometimes “API key.” Pick one and stick with it throughout.
• Headings should be parallel in style. Right now, some are commands (“Configure Your Authentication”), while others are descriptive (“Get Your Chimoney API Key”). Keeping them consistent improves readability. -
Improving the Reader’s Experience
• Add short explanations before or after code blocks to explain what’s happening. For example, before showing the Axios installation, you might add: “We’ll use Axios to make HTTP requests to the Chimoney API. Run the following command to install it in your project.”
• Think about the flow: readers should always know not just what to do but why they’re doing it.
Overall, you’ve got the right building blocks here, but the tutorial feels unfinished and a bit too high-level. With more context, smoother transitions, and some editing for clarity, this could become a strong, beginner-friendly guide.
This Pull Request contains my submission for the Chimoney Write-a-Thon Writing Challenge, focusing on the Multi-currency wallet transfer API endpoint.
I have created the three required deliverables:
use-case.md: Describes a real-world scenario for multi-currency wallet transfers.tutorial.md: Provides a step-by-step guide on how to use the API endpoint in code, including sample requests and responses.setup.md: Guides readers through the necessary authentication and environment setup to make a successful API call.All files are organized within the
submissions/multiwallet-transfer-queendolineakpan/folder, adhering to the specified challenge structure.I'm excited to contribute to documenting the Chimoney API and appreciate any feedback!
@phyleria
@adebayoileri