Versions Compared

Old Version 3

changes.mady.by.user Tripur Joshi

Saved on

compared with

New Version Current

changes.mady.by.user Tripur Joshi

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
  1. Email(star):  tripurjoshi3121@gmail.com
      - The chair of GitHub Make the Docs
      - Part AI Task Force

     

    1) PPT -     https://docs.google.com/presentation/d/1iFc-aQVHuJJ0IKxvqfL9TVFRIwB4zoAb/edit?usp=sharing&ouid=112303758644562594590&rtpof=true&sd=true
    2) GitBook (User Documentation Standard) - https://app.gitbook.com/invite/YiKRvybeEwfBWjowWoek/C3R7Xr7r5FM1n4qElKBK


Introducing "Making the Docs" to Mentees:


Title: Elevating Your Documentation Craft: Unveiling the Power of "Make the Docs"

Introduction: Greetings, fellow mentees! Today, we embark on an exciting journey that holds the key to transforming your documentation skills into something extraordinary. We're here to delve into the art of "Making the Docs." This concept isn't just about assembling words on a page; it's about crafting a meaningful, impactful, and user-centric experience through your documentation. So, let's explore why "Making the Docs" is a game-changer and how you can harness its potential in your journey as a technical writer.

Why "Making the Docs" Matters:

  1. Empower User Understanding: Consider documentation a bridge between complex technical concepts and your users. When you effectively "Make the Docs," you build a sturdy bridge connecting 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.


Unveiling the Essence of "Making the Docs":

  1. Empowering User Empathy: At its core, "Making the Docs" is about empathizing with your users. Think of yourself as a guide, leading users through the intricate landscape of technology. When you put yourself in their shoes, you're better equipped to create documentation that genuinely addresses their needs and concerns.

  2. Crafting User-Centricity: User-centric documentation is like a tailor-made suit—it fits perfectly. "Making the Docs" means designing content that not only educates but also engages. By doing so, you're not just relaying information; you're fostering an environment where users feel supported and empowered.

  3. Forging Lasting Impressions: A well-made document isn't just read; it's remembered. "Making the Docs" involves structuring content in a way that guides users through a logical sequence, from introduction to mastery. This sequential approach leaves a lasting impact and helps users retain information more effectively.

Harnessing the Power of "Make the Docs":

  1. Crystal Clear Clarity: Complexity can be daunting. Break down intricate concepts into bite-sized pieces. Use clear language, avoid jargon, and provide real-world examples to illustrate abstract ideas.

  2. Structured Your Story: Imagine your documentation as a story, with a beginning, middle, and end. Introduce topics, explain concepts step by step, and conclude with a meaningful takeaway. This approach helps users navigate your documentation effortlessly.

  3. Visual Symphony: Incorporate visuals to enhance comprehension. A picture is worth a thousand words, and a well-placed diagram or screenshot can illuminate a concept better than paragraphs.

  4. User-First Approach: Anticipate user needs and questions. Develop content that proactively addresses common queries, challenges, and pain points. By doing so, you're providing more than just answers—you're offering solutions.

  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.

Integrating "Make the Docs" into Your Daily Work:

  1. Plan with Purpose: Before you start, outline your documentation's purpose and target audience. This groundwork sets the tone for your content and keeps you on track.

  2. Collaborate Effectively: Don't work in isolation. Engage with developers, designers, and other stakeholders to ensure your documentation aligns with the product's vision and functionality.

  3. Iteration and Improvement: "Make the Docs" is a journey, not a destination. Continuously seek feedback, analyze user engagement, and iterate on your content to ensure it stays relevant and effective.

Conclusion: Congratulations! You've just tapped into the magic of "Making the Docs." Armed with this knowledge, you're equipped to craft documentation that goes beyond words, creating an experience that resonates with users and establishes you as a proficient technical writer. Remember, "Making the Docs" isn't just a skill—it's a philosophy that transforms information into inspiration.

So, let's embrace this approach, infuse your documentation with life, and watch as your work leaves a trail of informed and delighted users. The journey of "Making the Docs" begins now, and the possibilities are limitless!


                                                                        (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.