HN Explorer

Ask HN: How to document your work? how much is too much

2 points by random_kris ↗ HN
I've been working in a small office of mostly junior programmers. Until now we weren't keeping any documentation apart from word documents on shared drive... I've decided to change that so I am slowly building a documentation system for every project I work on. When it gets big enough I'll let others use / edit it... My question is how much is too much? Should I keep links to relevant info for each project (url to VMs, password etc...) or should I document every page that I create for a project. For example: project A is a CRUD app, with 2 form fields, and 1 datatable. Should I document every SQL query done inside application, every REST endpoint, every frontend component? Should I keep them together (so each page gets 1 frontend, 1backend, 1database doc) or should I split stuff between frontend / backend....

any good examples or design patterns that I could follow?

4 comments

[ 3.5 ms ] story [ 21.7 ms ] thread
lazyasciiart
Step 1: who is this documentation for? Non-technical users? Your colleagues and yourself when you come back to update it?

Step 2: for technical docs, the closer the docs are to the code, the more /likely/ it is to stay uptodate. What do you mean by "building a documentation system"?

random_kris
I have a folder with markdown files where lots of stuff is documentated -> I call this documentation system. Stuff is accessed via search or menu (im using mkdocs) Documentation is for me and colleagues (looking up passwords, various links, urls, tutorials etc..)
daleholborow
For anything rest API, I highly recommend you include Swagger/OpenAPI docs within your endpoint code, and don't bother to duplicate any of that material externally.
gshdg
Docs about code should go in code. That’s what comments and docblocks are.

Function signatures should be self-documenting. IMO API documentation is self-defeating for a small team because of how quickly it falls out of date.

Docs about design should go into either READMEs or a documentation system. Important trivia like URLs should too. (But don’t document every single URL any more than you document every function signature. Just make sure people know how to get to the staging system and the staff-only admin tools, etc.) Ditto for how-to docs.

Secrets should go into a password manager or something like AWS Secrets Manager.