Ask HN: Do you have READMEs or docs in your company? | Hacker News Reader

Ask HN: Do you have READMEs or docs in your company?

29 pointsanoncorpdev21 comments

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?

View on HN

LaTeX and git. Granted, we're a small company with five people in the tech department, all working the terminal most of the time, so we can choose pretty freely. We're a B2B company. Having solid, continuously improved, and useful documentation to put on the table at the first meeting is a huge win in trust and efficiency.

In 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.

> the critical success factor is having someone in the team that truly cares about it.

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.

Did him leaving have anything to do with the rest of the team not pulling their weight on documentation? ;-)

A downside of using a wiki for documenting software is that it can easily get out of sync with code. If your readme files and/or inline docs* are under version control, each commit can include both code and doc changes.

* 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

Wikis are great for intra-company documentation, although they do have a tendency to "rot" over time. If you're documenting code, a VCS that lets you check in documentation/wiki pages along with the code is a good idea (e.g. http://www.fossil-scm.org/)

We are using Github Enterprise so we have README.md files all over the codebase. They are pretty easy, if needed we can create wiki pages for each project.

Templated requirements and test plans. Fill in/extend the template to the needs of the project. In source,use project tag/ID for lines of interest.

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.

We use a combination of an internal wiki and formal documentation (our software is used to collect data during clinical drug trials for new drug applications, so certain FDA rules apply to our processes). Currently, the formal documentation is made up of Word documents (no, really) that are managed via projects in Team Foundation Server.

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.

We use DokuWiki (https://www.dokuwiki.org) and it's great, but as any tool, you have to be disciplined and keep the contents up to date, otherwise "wikis are where documentation goes to die."

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.

tl;dr: Yes we try to document through READMEs, wikis etc.

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.

Its not tough, you work with douchbags. I'm not trying to be rude here, I'm giving you some advice, change the habbits or leave, that kind of environment is toxic. "tight deadlines" when it takes 30 minutes to rewrite even a multiple page readme from scratch is a very poor excuse to not keep even the simplest form of documentation up to date.

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.

Internal use only code should be documented as well as any external facing code. It's easier to read through a readme or wiki than track down the person who owns or knows something about the code you want to use.

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 had a folder on the network called 'developer stuff'. I put up a DokuWiki a few weeks ago, and at the last developer meeting we gave each developer the task of creating one wiki article. It didn't matter what it was on, it was basically a catalyst to get them started using it.

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.

> 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.

We successfully adopted MediaWiki in our company and it was a really nice choice we made in early stage. We can easily search, tag pages, detect broken links etc.

I'll add another recommendation for MediaWiki. It is a good low-friction way to establish documentation for internal services and libraries. The markup syntax is rather idiosyncratic, but powerful enough for most of our needs. "Does it have a wiki page" is now a standard question for any new service or library in our shop.

On the biggest company I worked for (~200-250 people), we had a wiki. I think it was TRAC.

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...

We use doxygen + markdown for high-level documentation. This way you can edit the documentation in a text editor and put the markdown files in version control. And with graphviz and mscgen you can even create some standard graphs. The doxygen-generated html documentation is then put inside a wiki automatically.

We use MediaWiki, SharePoint Online, special repository for API documentation (private repo on github - it's convenient way to share with outsourcers), and sometimes we have readme in internal repositories also. I share opinion of our CEO, that 0 information should be stored just in somebody's memory.

Internal wiki is a great option.

And if you have the cash and freedom, hosted wiki's are also excellent. It is nice to delegate hardware admin for a wiki.

Reply on news.ycombinator.com