

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

Hi guys, I've been recently thinking about documentation process in a mega software company I'm working at.<p>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.<p>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?
======
halhen
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.

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

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

------
sdfjkl
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/>)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

------
aayala
Internal wiki is a great option.

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

