Friction Logs: Improving Onboarding for New Contributors

[vedansh-5]

How to do Introductions

Resolution

• Go to Introductions

• Click New Discussion

• Title the post with your name and write the introduction in the body.

• Suggested Improvement

• Add a section in the Contributing Guide or README explaining how and where to introduce oneself.

• Include a template for introductions to make it easier for newcomers.

Friction Logs for README Update

1> Initial Uncertainty: Scope of Changes

• Friction: The issue mentioned updating the README to "more accurately reflect the evolving mission," but it wasn't immediately clear what aspects needed to be modified beyond what was listed.
• Resolution: Clarified by referring to the issue description, which specified adding the mission statement, updating the image URL, and including build badges and a basic usage example.

2> Confusion Over "High-Level" Content

• Friction: The maintainer mentioned that the "high-level" description could be copy-pasted. The meaning of "high-level" wasn't initially clear.
• Resolution: Understood that "high-level" referred to the overview of the project’s mission and purpose, rather than detailed technical documentation.

3> Handling Relative vs. Absolute Links

• Friction: The README originally contained a relative link to the logo image, which needed to be replaced with an absolute link.
• Resolution: Updated the logo reference to https://github.com/The-AI-Alliance/gofannon/blob/main/gofannon.jpg as per the maintainer's request.

[rawkintrevo]

I'm seeing one issue and on 'general guidance' to be made from this:
Issue: Create clearer instructions for doing introductions
Guidance: Write clearer issues

@vedansh-5 do you agree?

[vedansh-5]

Clearer instructions for introductions would definitely help streamline the process. Following with you on the clearer issues part.

[rawkintrevo]

created friction logs category and moved discussion there

[vedansh-5]

Friction Log: Adding Links to Docs

Overview

While working on the project, I encountered an issue related to links in website documentation, specifically with relative URLs. There is a need for better clarification on how to correctly link documentation files in the website directory.

Problem Statement

Currently, contributors may struggle to understand the correct approach for adding links to documentation. The lack of explicit guidance on relative URLs can lead to incorrect references or broken links in the documentation.

Proposed Solution

Documentation covering:

• The correct way to add relative URLs in the project documentation.
• A reference to Jekyll documentation explaining relative links.
• A link to the _config.yml file in the website directory to the base url .
• An example demonstrating why the links are structured in a specific way.

Expected Outcome

This friction log will provide a clear and concise guide for contributors, ensuring consistency and accuracy in documentation links while reducing common errors.

[rawkintrevo]

added #168

[vedansh-5]

Improve Local Testing Instructions

Currently, the process for running tests locally lacks clear documentation, making it difficult to verify changes before opening a PR. Better instructions would help contributors ensure their code works as expected before submitting.
Adding a brief guide or a reference to existing steps would improve the workflow and reduce confusion.