You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 16 Next »

Introducing "Making the Docs" to Mentees:

Title: Unlocking Success: Mastering the Art of "Making the Docs"

Introduction: Welcome, aspiring technical writers! Today, we're diving into a crucial aspect of our craft that will elevate your skills and contribute significantly to your success in the world of documentation— "Making the Docs." In this session, we'll explore the essence of creating documentation that not only informs but also empowers and engages users. Let's journey to understand why "Making the Docs" is a powerful tool in your arsenal and how you can harness its potential.

Why "Making the Docs" Matters:

  1. Empower User Understanding: Think of documentation as a bridge between complex technical concepts and your users. When you effectively "Make the Docs," you're building a sturdy bridge that connects these two worlds seamlessly, empowering users to grasp intricate details effortlessly.

  2. Enhance User Experience: Documentation isn't just about conveying information; it's about crafting an experience. "Making the Docs" involves creating content that is accurate, easily digestible, intuitive to navigate, and visually appealing. By doing so, you're ensuring users have a positive and productive interaction with your documentation.

  3. Build Trust and Credibility: A well-made document reflects your expertise and dedication as a technical writer. Users are more likely to trust information presented in a clear, organized, and polishedly. This trust enhances your reputation and establishes credibility for both you and your organization.

How to Utilize the Art of "Making the Docs":

  1. Clarity is Key: Break down complex topics into understandable components. Use clear language, avoid jargon, and provide examples to illustrate concepts. Remember, your goal is to make the user's journey smooth and frustration-free.

  2. Structured Storytelling: Arrange content logically, following a structured narrative. Start with an introduction, move through the main points, and conclude with a summary. This helps users follow your documentation effortlessly.

  3. Visual Aids: Incorporate visuals like diagrams, screenshots, and videos to enhance comprehension. A well-placed image can often convey information more effectively than paragraphs of text.

  4. User-Centric Approach: Put yourself in the user's shoes. Anticipate their questions, concerns, and needs. Address common issues proactively to provide a comprehensive resource.

  5. Consistency and Style: Maintain a consistent tone, style, and formatting across your documentation. Consistency fosters familiarity and makes it easier for users to locate information.

  6. Feedback Loop: Encourage user feedback and iterate on your documentation. This loop helps you identify pain points, clarify ambiguities, and continuously improve your content.

Conclusion: Congratulations! You've taken the first step towards mastering the art of "Making the Docs." By understanding its importance and implementing the strategies discussed, you'll become a technical writer who doesn't just document information but transforms it into a valuable asset for users. Remember, each document you create is an opportunity to make a positive impact, so go forth and "Make the Docs" like a true pro!






-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

                                                                                                                                                                                         (star)  (star) (star)







Notes of meeting 25 July 2023

  • Make a presentation on integrating AI in Hyperledger workflow.




     User Documentation Improvements needed (for Solang)(I will add more points. Work in progress! (red star))
  • Introduction: The introduction section could be more informative and provide a brief overview of the Solang Solidity Compiler. It should clearly explain the purpose of the compiler, its features, and its compatibility with other Solidity compilers.
  •  Add Visuals: The addition of visuals is needed like
                                     - screenshots of code snippets for making it more interactive.
                                     -  flowcharts, and block diagrams for better Understanding.

There are many options available for creating diagrams. Three options that are free or have free options include:

Section-wise improvements in the documentation after the introduction:
  • Installing Solang:

    Remark - The installing section is not beginner friendly. It is challenging for a user who wants to try it out and learn about it. The first step of setting up should be easy, not overwhelming. 
    Improvement suggestion - 1. Redesigning the section and making it more simple.                
                                                            2. Adding screenshots for specific devices.
                                                            3. The language used is using too many technical terms without any explanation about them, we can define them and make it more noob-friendly.


(lightbulb) Work Flow 

Attended 16th June 23 Solang Community meeting.

  •  The members need a lot of help with the documentation. 

They have the following requirements: 

  1) Want beginner-friendly documentation of Solang.
  2) Tutorial on how to set up Solang in different operating systems like macOS, Linux, etc. (Setting Up Your Development Environment for Solang: A Step-by-Step Guide)
  3) Getting Started with Solang: A Beginner's Guide. 
  4) Building Projects with Solang: A Comprehensive Tutorial
  5) Developing Smart Contracts on Solang: Step-by-Step Guide (Solang Basics: An Introduction to Solidity-based Contract Development)
  6) Invoking Nested Contracts: A Guide to Calling Contracts within Contracts
  7) Comprehensive Guide to Writing, Testing, and Deploying Smart Contracts in Solidity with Solang
         (Understanding Solang Syntax and Solidity Concepts for Beginners, Testing and Debugging Smart Contracts with Solang: Best Practices for Beginners)
  8) Writing Your First Smart Contract with Solang: A Hands-On Tutorial
  9) Exploring Advanced Features of Solang: A Next-Level Guide for Beginners
 10) Solang Security: Tips and Best Practices for Beginner Developers
 11) Solang Tools and Utilities: Enhancing Your Smart Contract Development Workflow for Beginners


(blue star) Suggestions (blue star)

1. While making changes in the documentation, we can follow the Google developer documentation style guide: https://developers.google.com/style

  • Helpful in maintaining uniformity throughout the documentation.

2. For flowcharts and diagrams, we could use Draw.io: https://app.diagrams.net/

  • We can do real-time collaborations.
  • It has a beginner-friendly interface and pre-made layouts.
  • No labels