For the couple projects that I’m working on lately, the readmes were decently up to date. I took the time to carefully read through them and try to ascertain if there was something that was confusing or too involved, which made me update a couple of processes and their section in the readme reflected that.
Also had to create a couple of tasks in the backlog for the simplification of the makefile of one of them, as just with a read of the README you could see that the makefile was overly complex, when it should be an abstraction of the complex things, and not complicating the project more. So that was fun!
For internal projects I prefer to keep the README as short as possible (as it is simpler to keep it uptodate) but long enough to help the repository to survive.
Well, I was a type of programmer who never used comments and never kept a well maintained readme for the project. But, soon I realised that we are writing code for our future self as well as for other team members to understand and realised the importance of good documentation for understanding of any project. Hurray, I updated the readme of the project I am currently working on
README is very important yet it’s easily be ignored. Every time I joined a new team, I would read most of the README docs first.
The project I’m currently working on has an okay README except for some outdated links.
Hello folks, for the day one, I added Readme for an application that I build an year back to exploring shrine ruby gem.
All work took me twenty minutes exactly. GitHub - anubhav8421/exploring_shrine is the link to the github repository.
The documentation is not extensive. Tried to keep it minimal.
Planning to add more info sometime this weekend
It was kind of eye-opening seeing how out of date our project README was. I thought it was nice and detailed while providing just enough information to get a developer started. However, wrong version references, out-of-date links, etc. won’t help anyone. We got a good bit updated this morning, and I feel much more confident that developers new to our internal project will start off on better footing now.
Our README was in surprisingly good shape. I did take the time to verify the info was up-to-date, and to schedule some time with the team to talk about a section that may not be relevant anymore.
Went through the README for our main application. Found a couple spots where some of the dev and deploy processes had fallen out of date. One of those things that we need this kind of push to actually make the improvement!
This is my second time going through the challenge, it’s like spring cleaning!
Wow, those 20 minutes flew by. Used them to make progress on fleshing out a README for a newer project. Still some work to be done, but glad I spent the time on it–those examples were very helpful!
Great day 1! The README of our product had been untouched for two years and was in dire need of some TLC. Adding a few useful links to tools used and random bits of knowledge will go a long way.
I took time today and updated a README for a closed-source project where I am the only programmer. It’s easy to neglect those documents because you’re holding the domain in your head. Writing the README is an investment in yourself, your project, and (fingers crossed) your future team.
Thank you moderators and fellow CQC-ers for being here.
Meta task: What projects do or don’t even have READMEs?
A little script and I end up with 25 of the 141 apps don’t. A bit more than can be created in 20 minutes, but I created one, and now have a list to pick through.
Since I’m working on internal applications my audience is mostly myself and my team, not external folks. The two most important aspects for me beyond what is discussed above (dev/deploy/etc) are:
schedule - This could be programmatic (cron, etc), or just seasonal things that the users tend to do.
context - What things beyond this application is it connected to? Databases, APIs, other internal applications, processes, departments. Knowing how this app relates to the broader environment is often as helpful guidance as anything about the internals of the application.
First time doing a CQC and this day was a good one. Updated our product README with some links to documentation that I have found helpful several times. Also removed some crusty bits of it as well!
