These sorts of discussions are a great reason to do the CQC with a coworker/friend 
1 Like
Our README was in pretty good shape, information-wise. There are some setup steps I’d like to see automated, but that may be for another exercise 
I did the following in my 20 minutes, instead:
- Linked to a couple of third-party libraries we ask developers to install locally to help with Ruby code quality
- Reformatted inline code blocks for consistency (backticks for all code inlined in paragraphs; Github-flavored Markdown for multi-line blocks)
- Found and fixed one typo!
1 Like
I picked one of the microservices we use at the company I work at. The readme was already in decent shape, so much of the 20 minutes for me was:
- Fleshing out overview info
- adding technical requirements
- running the markdown through markdownlint (https://github.com/markdownlint/markdownlint) and correcting the issues
2 Likes
Excellent use of my time today! I am a solo developer most of the time, so the readme in quite a few projects was still the boilerplate from the framework install. However really still need to have this updated if not for the “in case I get hit by a bus” use case, but also for the “need to pick back up a project” use case.
1 Like
We have a project that contains shared linters, style guides, setup scripts, etc that had the default README. The explanations for setup and linting were all over the place across our projects, so I copied them into the place where the actual configs are stored and expanded on them on a bit. Great first day!
1 Like
Filled out our README and created a PR here: https://github.com/ManageIQ/manageiq-api/pull/264. It needed a lot of love (there was not only no useful information there, but false information!), so took a bit longer than 20 minutes! But really glad to have done this - it even closes an existing issue! 
1 Like
A group of us (5 or so) hopped on a call and greatly improved our README from having very little information to at least having links to places where we’ve internally documented things. Successful first day!
2 Likes
I created a README for the main project at my company. Filling it out is taking much longer than 20 minutes, as setting up the project is very complex.
2 Likes
I have the longest tenure at my company at just over a year, but the code base is 6+. This exercise really helped highlight some of the tribal knowledge I’ve gained that was never written anywhere. That is a path I still need to take, but at least some is now recorded!
3 Likes
When onboarding a new project I always follow the setup instructions in the README. If I find that something is missing, I submit a good first PR to improve it. It’s always a good place to start.
I had already taken the time to update the README for a project I’m currently working some time ago, but now I found new ways to improve it!
We have a few documents for setting up the project development and production environment. Since I’ve picked an embedded project, these files are pretty complex and I do find docs and pdf to be easier to write, maintain and read than .md files.
I created a small readme file in the main FW repository to point to all the relevant documents and links (e.g. JIRA, SharePoint, Confluence etc)
This readme turned out to be a nice starting point to easily find all the required information for the project
2 Likes
Thumbs up on calling attention to this often over-looked on-boarding tool. Great start.
Great! It works for me. I had to force me to write down everything that was only in my head. At the beginning I think, ok I have in my head I’ll write it down at the end of the project, but when I take that 20 minutes to write it down it helps me to organize some things that I have pending to establish.
1 Like
I recently opened a PR to create a bin/setup script for one of our applications. Having a setup script helped to clean up with README. The code review for my PR had some feedback, so I used my 20 minutes (plus some) to accommodate these changes.
Even with this change, we still have more work to go!
Happy I listen to Art of Product, and know it’s okay that I don’t feel 100% satisfied with what I did with my 20 minutes today. It’s a win just making progress!
Thanks, Ben
2 Likes
Great! The example README was great. I updated a project of mines that I’m starting back development on this week. While I’m still the only developer on it, it was great to everything out my head especially things I’ve overlooked as the sole contributor.
1 Like
Great start 
Most of our documentation lives in our Github wiki, and so I spent some time improving some of our articles there. Specifically, I flushed out our instructions on how to set up the database and how to test.
I think the most valuable part of this was that I noticed I have a lot of private notes that detail things we don’t have specific instructions for in our Wiki. Things from how to create a hotfix to how to use rspec bisect and try to fix flaky tests. I’ll work on getting that stuff into our wiki for others to use as well!
1 Like
.This was a hugely helpful exercise for our team today. I had no idea how out-of-date our README had gotten, and it’s timely since we’re looking at some new hires soon.
I tried to write the “Welcome!” doc I wish I’d had when I started, and even with just 20 minutes I got pretty close. I added a few TODOs and shared it out the rest of the team to solicit some additional PRs. Looking ahead at tomorrow’s challenge, they’d better get their suggestions in quickly.
Thanks Ben, and thanks everyone for sharing your experiences!
1 Like
I just started a new project and hadn’t gotten around to doing a readme yet. This was really helpful in figuring out what basic information to put on there.
Having a small Front end team, our frontend readme was a bit bare.
I sorta cheated but decided to flesh out docs by adding a deployment section to the readme that links to a new deployment doc. Deployment is one of the most common things I get asked about.
The new deployment documentation is much better now, even though it has some work left to do
1 Like