Skip to content
Advent of Open Source

Day 3: Illuminating the Path

The Fog of Confusion Descends

As dawn breaks over the Winter Open Source Village, a dense fog rolls in, shrouding the landscape in uncertainty. The Keeper of the Repos gathers the villagers, his voice steady but filled with concern.

The Mist of Misunderstanding has come upon us,

they warn, pointing toward the thick haze enveloping the path.

This fog clouds the minds of artisans, making it difficult to navigate the tools we’ve forged and understand their purpose.

The villagers murmur in fear, unsure of how to proceed. The Keeper raises his hand to silence them.

But there is hope,

they continue, a glimmer of determination in their eyes.

In the archives of the village lies an ancient remedy—a guide. These scrolls, when crafted with care, will cut through the mist and reveal the way forward.

They gesture toward the nearby scrolls, worn but still vibrant with potential.

By creating these parchments, you’ll guide the artisans through the complexities of our work, ensuring none are lost to the fog.

With a firm nod, the Keeper looks at you, as if seeing you for the first time.

Your journey begins now. Lay the foundation for these parchments. Start small, but ensure that, over time, they grow into the guiding scrolls that will lead others clearly and confidently through our village.

Choose the rune that best suits your skills and experience:

If you’re joining the village today, you can always catch up on the instructions from Day 1 to get up to speed.

Beginner: Create Your First README

Snowflake rune
Beginner level for folks starting a new artifact

The Keeper of the Repos hands you a blank scroll, its edges crisp and untouched. Their eyes meet yours with an encouraging gleam.

This is your canvas,

they say, their voice calm but firm.

Every great artifact begins with understanding, and that understanding starts with you. Your task is to capture the essence of your work—the heart of your creation—on this very scroll.

They gesture toward the scroll with a reverence that suggests its importance.

A well-crafted Scroll of Beginning acts as a beacon,

the Keeper continues,

welcoming those who approach and illuminating the path forward. It is the first thing that many will see, the first glimpse into the spirit of your artifact. It serves not just as an introduction, but as a guide, gently leading others through the purpose, the steps, and the tools of your endeavor.

The Keeper pauses, allowing the weight of their words to sink in.

This scroll is more than just instructions—it’s a warm invitation, a first handshake with your community. Make it clear, make it inviting, and make it a map that points to the future.

They hand you a quill, its nib shimmering with possibility.

Now, the work begins,

they say with a knowing smile.

This scroll will be the foundation, the starting point for those who will walk with you.

README files are the first thing visitors see when they land on your project’s repository. They provide an overview of your project, its purpose, and how to get started. A well-crafted README can attract contributors, users, and collaborators to your project, setting the tone for a vibrant community.

  1. Edit your README.

    From your project repository, click on the README.md file, then click the pencil icon to edit it.

  2. It is time to start writing your README.

    From here, you can start writing the content of your README using Markdown syntax. You can refer to this Markdown Guide that will help you format your text. Don’t worry, you’ll master it in no time!

  3. Structure your README.

    There is an infinite number of ways to structure your README. Let’s start with common sections, and this README will be updated along the Advent of Open Source:

    • A main title with the project name
    • A more complete description of your project compared to the repository description which is character-limited
    • A dedicated section to remind the license under which your project is distributed

    In the following template, elements between <!-- --> are comments and won’t be displayed in the final README.

    Please copy and paste the following template into the interface, and replace the placeholders with your project’s information:

    README.md
    # Project Name
    

    Description of you project goes here.
    

    ## License
    

    This project is licensed under the <!-- Insert your licensing type (e.g. 'MIT') --> License - see the [LICENSE](LICENSE) file for details.

    There is no standard format for a README. Feel free to adapt, add, modify, or remove these sections based on your project’s needs.

  4. Check and preview your README.

    Verify that your content is correct. Here’s an adapted version based on our template for the Avalanche fake project:

    README.md
    # Avalanche
    

    Avalanche is a community-driven initiative designed to help The Winter Open Source Village rediscover its spirit of collaboration. As Open Source projects grow, they can sometimes lose the sense of unity that makes them thrive. Avalanche seeks to bring contributors back together, fostering a culture of teamwork and shared purpose. Whether you're a first-time participant or a seasoned contributor, Avalanche provides the tools and guidance to help everyone work in harmony.
    

    Through interactive challenges, mentorship, and open discussions, Avalanche creates an environment where contributors can connect, collaborate, and build exciting projects. It's not just about writing code; it's about building relationships and strengthening the bonds that make Open Source vibrant. Join Avalanche to help The Winter Open Source Village flourish as a beacon of collaboration and creativity.
    

    ## License
    

    This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

  5. Click on the Commit changes button to save your README.

  6. Change the commit message to docs: update README.md.

  7. Click on the Commit changes button to finalize the update.

  8. Your README is now updated.

    Go back to your repository’s main page and check that your README is displayed correctly. The link to the license should be clickable.

Your README is now way better than a blank page! It’s the first step in creating a welcoming environment for your project, and it will help others understand its purpose and how they can contribute.

Success Criteria

  • ✓ You maybe learned how to write in Markdown.
  • ✓ Your README is clear, readable, and explains the purpose of your project.
  • ✓ The license information is included and linked to the actual license file.

Your Scroll of Beginning is no longer blank, though it is not yet complete. It is the symbol of a new beginning, a foundation upon which the journey will be built. The essence of your artifact now dances across the parchment in words, capturing its spirit and purpose. This is the first step in creating a guide for those who will follow, a lantern that will lead travellers through the many paths that your work will take them on. It’s not just a parchment of guide—it is a living, breathing part of your artifact’s heart, ready to be discovered and understood.

The Keeper of the Repos looks upon your work with a nod of approval.

The journey begins with clarity,

they say.

This scroll is the first of many that will help others find their way in your world. Let it be a guiding star that will illuminate the path for those who come after.

The Keeper’s Wisdom

A guide filled with insight is like a lantern that cuts through the darkest fog. It offers a way for others to see clearly, to understand what has been created, and to know how they can be part of it.

Take up your quill and dispel the Mist of Misunderstanding. As you continue, remember that the light you cast will guide others toward the heart of your creation. Tomorrow brings a new task, and with each step, the way will become clearer.

Intermediate: Audit and Enhance your README

Snowball rune
Intermediate level for folks wanting to enhance an existing artifact

The Keeper of the Repos leads you to a glowing tome on a pedestal. Its light flickers weakly, struggling against the encroaching Mist of Misunderstanding.

This is the Pathfinder’s Tome,

the Keeper explains,

It is meant to guide those who delve deeper into the craft, but its clarity has faded. Without it, even seasoned travellers may lose their way.

They place a hand on the tome.

Bring order to its pages. Strengthen its words so they shine like a lantern, cutting through the haze and guiding all who seek to contribute.

The Keeper steps back, leaving the tome in your care.

Your repository already has a README—that’s great! It means you understand the importance of documentation. But just like code, documentation benefits from refactoring and enhancement.

Today, we’ll transform your README from a basic introduction into a comprehensive resource that welcomes contributors, guides users, and showcases your project professionally.

A well-crafted README acts as your project’s landing page, documentation, and community hub. It’s often the first thing potential users and contributors see, so it needs to make a strong impression while providing clear, actionable information. Projects with clear, comprehensive documentation tend to attract more contributors and users, as they lower the barrier to entry and demonstrate project maintainability.

  1. Audit your current README

    1. Check the existence of these essential sections

      • Project description and purpose
      • Installation instructions
      • Usage examples or code snippets
      • Contributing guidelines or links to CONTRIBUTING.md
      • License information and link to the actual license file

    2. Think about other sections that would be relevant to your project and add them as needed. For instance:

      • A table of contents for easier navigation
      • Some screenshots or GIFs to showcase your project or its features
      • A “Quick Start” section for new users
      • Add a troubleshooting section or FAQ if you have common issues

    3. Link everything from your README. For example, consider adding links to:

      • your Code of Conduct
      • your contributing guidelines
      • your documentation
      • issues creation page
      • the GitHub discussions, or any other community platform
      • the social media accounts of your project
      • similar projects or inspirations

  2. Add badges to your README to enhance its visual appeal and functionality. Badges are small images that provide quick information about your project, such as build status, code coverage, version, license, and more. They can be added to your README using Markdown or HTML.

    The ideas of badges are endless, but here are some common ones:

    • Build status: Shows whether your project’s build is passing or failing.
    • Code coverage: Indicates how much of your code is covered by tests.
    • Version: Displays the current version of your project.
    • License: Shows the type of license your project is distributed under.
    • Contributors: Displays the number of contributors to your project.
    • Last commit: Shows when the last commit was made to your project.
    • GitHub issues: Displays the number of open issues in your repository.

    You can generate badges using services like Shields.io, Badgen, or other badge generators.

Your README is way better now, isn’t it? But there is still room for improvement. Keep iterating on it, and remember that it’s a living document that should evolve with your project.

Success Criteria

  • ✓ Your README includes essential sections like project description, installation instructions, and usage examples.
  • ✓ Your README has links to contributing guidelines, Code of Conduct, and other relevant resources.
  • ✓ Your README includes badges that provide quick information about your project.

The Pathfinder’s Tome now glows steadily, its pages vibrant with clarity. The Mist of Misunderstanding withdraws, unable to obscure the light you’ve restored.

You have strengthened this guide,

the Keeper says, their voice filled with approval.

Now it will lead travellers forward with confidence, scattering confusion and doubt.

Villagers gather to explore the tome, their expressions bright with newfound understanding. The Keeper smiles.

A clear guide inspires action. You have ensured this path will welcome all who follow.

With the Mist retreating, the Pathfinder’s Tome stands as a beacon of purpose.

The Keeper’s Wisdom

A guide filled with insight is like a lantern that cuts through the darkest fog. It offers a way for others to see clearly, to understand what has been created, and to know how they can be part of it.

Take up your quill and dispel the Mist of Misunderstanding. As you continue, remember that the light you cast will guide others toward the heart of your creation. Tomorrow brings a new task, and with each step, the way will become clearer.

Advanced: Create a README Ecosystem Mapping

Ice rune
Advanced level for folks wanting to enhance an existing large artifact or several org/personal artifacts

The Keeper of the Repos guides you to the heart of the archives, where the Great Mechanized Atlas lies dormant. Its intricate gears are still, its pages scattered and incomplete.

This is the Atlas,

the Keeper begins.

It has the power to connect every piece of knowledge, creating a map that shows how all parts of the craft come together. But the Mist of Misunderstanding has disrupted its harmony, leaving travellers lost.

They turn to you with a steady gaze.

Your task is to restore the Atlas. Bring clarity to its connections, ensure its design reveals the whole picture, and let it guide even the most complex journeys.

The Atlas hums faintly, waiting for your touch.

For maintainers managing multiple repositories or complex Open Source projects, your README is more than documentation—it’s a strategic communication tool that bridges projects and attracts contributors.

  1. Create a cross-repository README strategy by transforming your documentation from fragmented to interconnected.

    The first option is to create a dedicated repository with its own README that would be a central repository that acts as a hub for your project ecosystem. This repository would contain a README that links to all your other repositories, providing a high-level overview of your projects and their relationships.

    • Visualizes relationships between your repositories
    • Explains the purpose and interaction of different projects
    • Provides a clear architectural overview of your ecosystem
    • Links to detailed documentation for each sub-project
    • Prevents documentation fragmentation and simplifies navigation for contributors across multiple projects

    The second option is to rely on profile or organization profile README.

  2. Explore dynamic documentation automation could be implemented via GitHub Actions to render some parts of your READMEs dynamically.

    These automation tools reduce manual work and keep your README accurate and up-to-date with minimal effort.

    With complex projects, it’s easy for documentation to fall out of date. Automating parts of your README, like the contributor list or dependency graph, ensures that the documentation remains fresh and accurate without relying on manual updates.

Success Criteria

  • ✓ Central hub repository or profile README that links to all your projects.
  • ✓ (Optional) Dynamic visualization of your project ecosystem (e.g., with Mermaid diagrams).
  • ✓ Explored dynamic documentation automation using GitHub Actions.
  • ✓ Clear and concise architectural overview that connects multiple repositories and guides potential contributors through the ecosystem.
  • ✓ Dynamic content (e.g., contributor list, dependency graphs) that automatically updates with each change.

The Great Mechanized Atlas awakens, its gears turning smoothly as its pages align into a cohesive map. The Mist of Misunderstanding shrinks back, powerless against the clarity you’ve restored.

You have repaired what few could,

the Keeper says with admiration.

The Atlas now reveals the full scope of the craft, offering a complete guide to those who seek to understand it.

Villagers marvel at the Atlas, its intricate design connecting every detail into a unified vision. The Keeper smiles.

With this, no part of the craft will go unseen. You’ve created a tool that will inspire and empower all who follow.

The Atlas glows brightly, a symbol of understanding and connection.

The Keeper’s Wisdom

A guide filled with insight is like a lantern that cuts through the darkest fog. It offers a way for others to see clearly, to understand what has been created, and to know how they can be part of it.

Take up your quill and dispel the Mist of Misunderstanding. As you continue, remember that the light you cast will guide others toward the heart of your creation. Tomorrow brings a new task, and with each step, the way will become clearer.