
Ask HN: How do you document your code at work? - Jaxkr
This has been different at literally every company I&#x27;ve worked at, and it&#x27;s never been good.<p>Specifically curious about how internal technical&#x2F;code&#x2F;product documentation is written and maintained.<p>If you like the internal documentation at your company: what&#x27;s so great about it?
======
byoung2
Every new feature at TrueCar requires extensive documentation. A lot of our
libs are open source so they need good docs. Here is an example of our UI
component library's docs:

[https://www.truecar.com/battery-
pack/introduction](https://www.truecar.com/battery-pack/introduction)

~~~
billconan
how to make sure code and doc are in sync? who reviews doc changes?

~~~
gtirloni
I often get these questions from agile people (not saying you're or aren't)
and my answer is always: the same code reviews that ensure there aren't code
smells. Lack of documentation is a code smell to me.

To be clear, if docs are just translating to English what the code is already
expressing then they are bad. They should be high level, explaining odd cases,
etc. If they go out of sync, you fix them because your future ability to
understand the code depends on it.

I've had PR's rejected because they only added comments saying that "they will
get out of sync". I've had documentation projects canceled because "they will
get out of sync". It makes me really sad when a new hire struggles to
understand basic things in our code base. </rant>

------
thisistheend123
I guess putting detailed comments within the code are the best form of
documentation.

The flow of code and detailed comments about it right there in the flow help
the readability of code. Also it's easier to change the comments when code
changes because its all there in a single file. Makes reviews easier.

