DEV Community

Aman Shekhar
Aman Shekhar

Posted on

I paid people to try and follow my README

#ai #machinelearning #techtrends

I recently found myself knee-deep in a personal experiment that turned out to be more enlightening than I expected—so much so that I can't wait to share the details with you. Ever wondered what happens when you pay people to follow your README? Yeah, I took that plunge, and let me tell you, it was a wild ride.

The Backstory

As a developer, I’ve always put a premium on documentation. I mean, nothing feels worse than diving into a project only to wade through a jumble of half-baked instructions. So, I decided to put my README to the test. I thought, “What if I could get real users to follow my README and see what breaks?” I created a small project, wrote what I thought was a solid README, and offered a few bucks on a freelance platform for anyone willing to give it a shot.

The Experiment Begins

I’ll admit, my initial excitement was tinged with skepticism. Would folks actually follow it? Would they get frustrated? I was ready for answers. The first few hires were enthusiastic but somewhat bewildered. I provided them with a simple React app I had built to manage tasks—nothing too complex. I figured it would be a great test case since managing state and props can sometimes trip even seasoned developers.

One of the first testers, Sarah, reached out almost immediately. “I love the concept, but I got lost at step three,” she said. That’s when my “aha” moment hit me. It wasn’t just about whether they could follow the README—it was about the clarity and usability of my instructions. I thought my explanations were straightforward, but clearly, they weren’t resonating.

Lessons from the Trenches

As more testers came on board, I started to see patterns. Almost every one of them faced similar hurdles, particularly around setting up the environment. They stumbled at the Node.js installation step. I realized I’d glossed over the version requirements. It’s like giving someone a map with missing roads—how do you expect them to get to the destination?

So, I updated the README to include prerequisites and even referenced common pitfalls. The lesson here? Always think like a complete newbie. You might be deep in the weeds, but remember: it’s their first time.

The Code Behind the Chaos

Here’s a snippet of my original README:

## Installation
1. Clone the repo
2. Install dependencies
3. Run the app
Enter fullscreen mode Exit fullscreen mode

Sounds simple, right? But here’s how I revised it:

## Installation

1. Clone the repo
Enter fullscreen mode Exit fullscreen mode


bash
git clone https://github.com/yourusername/yourproject.git


2. Ensure you have Node.js version 14.x installed. If you're not sure, check by running:
Enter fullscreen mode Exit fullscreen mode


bash
node -v

   If you need to install it, you can download it from [nodejs.org](https://nodejs.org).

3. Navigate to the project directory:
Enter fullscreen mode Exit fullscreen mode


bash
cd yourproject


4. Install dependencies:
Enter fullscreen mode Exit fullscreen mode


bash
npm install


5. Run the app:
Enter fullscreen mode Exit fullscreen mode


bash
npm start

Enter fullscreen mode Exit fullscreen mode

It’s all about providing the right context. My original README lacked depth, and simply adding version checks helped streamline the process significantly.

The Feedback Loop

As I received feedback, I learned that some users preferred video tutorials over written instructions. That struck me! What if I could create a short video walkthrough alongside my README? It’s like giving users a roadmap with a GPS, guiding them step-by-step. I recorded a quick screencast of the entire setup process and tucked it right into my README. The response was overwhelmingly positive—people felt more empowered and less frustrated.

Reflecting on the Experience

If there’s one takeaway from this experiment, it’s that the development world thrives on collaboration. Getting outside perspectives is invaluable. It’s easy to fall into the trap of thinking your code and instructions are crystal clear because you’ve been living in that world. But bringing in fresh eyes can reveal the gaps you didn’t even realize existed.

Final Thoughts

So, would I recommend this approach? Absolutely! It’s a brilliant way to not only improve your documentation but also to engage with the community. Sure, it requires some investment—both time and money—but the insights gained are worth their weight in gold. If you’re feeling adventurous, why not give it a shot yourself?

I’m genuinely excited about the potential for better documentation in our field. It’s like opening a door for others who want to explore the same projects. After all, we’re all in this together, right? If we can make our paths clearer, we’re doing our part to uplift the entire development community.

Looking ahead, I plan on implementing user feedback more consistently, possibly even setting up a regular feedback loop. Who knows? Maybe my next README will be a collaborative effort. If you’ve got thoughts or experiences to share, I’d love to hear them. Let’s keep the conversation going!

Connect with Me

If you enjoyed this article, let's connect! I'd love to hear your thoughts and continue the conversation.

Practice LeetCode with Me

I also solve daily LeetCode problems and share solutions on my GitHub repository. My repository includes solutions for:

  • Blind 75 problems
  • NeetCode 150 problems
  • Striver's 450 questions

Do you solve daily LeetCode problems? If you do, please contribute! If you're stuck on a problem, feel free to check out my solutions. Let's learn and grow together! 💪

Love Reading?

If you're a fan of reading books, I've written a fantasy fiction series that you might enjoy:

📚 The Manas Saga: Mysteries of the Ancients - An epic trilogy blending Indian mythology with modern adventure, featuring immortal warriors, ancient secrets, and a quest that spans millennia.

The series follows Manas, a young man who discovers his extraordinary destiny tied to the Mahabharata, as he embarks on a journey to restore the sacred Saraswati River and confront dark forces threatening the world.

You can find it on Amazon Kindle, and it's also available with Kindle Unlimited!

Thanks for reading! Feel free to reach out if you have any questions or want to discuss tech, books, or anything in between.

Top comments (0)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.