Ask HN: Do you have READMEs or docs in your company?
Hi guys, I've been recently thinking about documentation process in a mega software company I'm working at.
Our team mostly does not write documentation and other teams rarely do. Since our team is writing internal-use-only code, I couldn't convince anyone to write documentation for projects.
We don't have a good documentation system (e.g a MediaWiki). SO, how do you guys manage documentation process at your company? Is it a wiki, or README.txts or something else?
21 comments
[ 1.6 ms ] story [ 110 ms ] threadIn my experience, the critical success factor is having someone in the team that truly cares about it. In our case, we had a guy whose peace of mind depended on having everything in order, including well-structured, complete, and correct documentation. He left us a couple of months ago, and already the documentation is starting to deteriorate.
Entirely true. In my last job, I was that person. In my current job, I care about it, but in a sort of different manner. My personal documentation is great (or so I'd like to think), but I don't push for other people to post their documentation unless it's something they're trying to ask me to do by following the documentation.
As a result, documentation is sparse, even though they lament the lack of documentation for services.
You need someone who takes ownership for documentation. Whether it's a self-appointed task or a dedicated employee, if you're missing that you'll be missing documentation.
* If your software is exposing an API to others in your company, you might want to look at Javadoc and other languages' equivalents: http://en.wikipedia.org/wiki/Javadoc
We use: internal wiki (confluence), readme's, rdoc - javadoc - etc., PR's on github enterprise
This works pretty well. For reference we have hundreds of devs. Most of the time you can find some sort of documentation in at least one of the above locations.
We are currently moving in the direction of using JSDoc on our latest project (since it is entirely written in JavaScript), and we will likely have our internal auditors sign off on the format for use as our software design docs.
It's started to grow pretty fast so I hope it works out for us. We're probably going to have an intern or junior developer move documents from the old folder to the new system.
Just be careful not to give them all of the shit jobs.
Sometimes requirements documents explain more than the code or comments. IE: 12345_r.doc User needed X for 2012 tax reporting because of leap year due to the extra day in the year vs accounting's actual 30 day per month business rule.
Comments/code would say something along the lines of '/* Project 12345 - Check for leap year */ if tax report and year eq mod4, bit shift left topic 2'
It is outdated, but it works. Documents add accountability. Link in emails, project team, sign-offs, etc.
Most comments tend to cover only code comments or API documentation, but a company has way more documentation than just that: there are policies, procedures, minutes, tutorials and documentation which relates to code but does not live within it.
Documentation is hard. not because there aren't enough good tools. there are plenty actually. Problem is: how to keep them updated with frequent changes in code, enhancements, business process changes etc. At very large companies with distributed teams across the globe (I work for these kind of companies), maintaining an updated documentation/readme is the challenge. Do you want to spend the time to update the doc. on every release, every ehnahcement, every production fix, short term/long term projects etc OR you want to deliver the product on tight deadlines. Now once a project is delivered, do you want to go back and updated READMEs ? Wait, I had a piece of code that I delivered in release x.y in New YOrk and wrote a nice README. A developer in London made some changes to it 6 months later but he never updated the documentation on that specific change or perhaps did not know where my README was or perhaps did not care enough. Now my README is outdated and pretty much useless. Very tough.
I know its much harder than that to just leave so I would suggest at the least: not accepting code changes from some out of town baddie who obviously doesn't respect you or your work. Trust me if your boss asks why you didn't merge and you say "he didn't spend 30 minutes to update the docs to reflect the changes" they will take your side, bosses care about future proofing and best practices being followed believe it or not.
Fortunately, most developers were responsible enough to update the pages when they did something relevant (i.e., if you created a script to automate certain process, you'd put it on that process's page). I suspect that this is not very common...