Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: How To: Internal Documentation?

news.ycombinator.com

Post reply on HN
Print view View original

11–20 of 53 posts

Re: Ask HN: How To: Internal Documentation?

#11

Post by Terr_ »

cedws wrote: post #6

Docs should be as close to source code as possible, ideally in the same repo so they can be updated and reviewed in the same PR as the source changes themselves. Markdown works fine. For docs that don’t relate to source, just have a repo for general docs. Not only is Confluence absolute crap, tech docs in it rot because it’s a separate system developers don’t want to use. Similar story for MediaWiki.

I would also strongly favor documentation diagrams which can be rebuilt from "code", such as PlantUML, Mermaid, and the venerable GraphViz formats.

Re: Ask HN: How To: Internal Documentation?

#12

Post by Terr_ »

The blank-slate of a new hire is a valuable resource which will (ideally) not remain for long.

They will essentially be testing your guides, and you should plan for existing developers to spend a little time fixing issues found by your impromptu tester.

Re: Ask HN: How To: Internal Documentation?

#13

Post by theelous3 »

New hire checklist repo that the hire forks and works through.

guru is excellent too imo. docs can be set to expire which serves well if you actually want to update them regularly, or just give a marker for readers to be a bit cautious about the validity of the content.

Re: Ask HN: How To: Internal Documentation?

#14

Post by m3nu »

In Bookstack organized by department. Simple to update and put access controls on it.

As others have mentioned, this needs to be a living document and the person doing the task needs to update the docs where needed. No tool can replace this, but Bookstack at least makes it easy.

Re: Ask HN: How To: Internal Documentation?

#15

Post by muzani »

Huawei. They have system analysts, who are basically living documentation. There's also some overlap with 'team lead' in western orgs and I'd say they have similar pay. These folks are idle by default; they're meant to be interrupted and their main focus is mentoring. They also handle a lot of the PRs, code quality, documentation.

It's also not hard to onboard someone into the same role. They took me on for a similar role and it took me about a few weeks to be familiar with nearly all the code I was responsible for.

Re: Ask HN: How To: Internal Documentation?

#16

Post by benrutter »

I've seen it done really well, really badly, and not at all!

Here's some things that I think help

- Tie documentation to code wherever possible: Automated API documentation is an obvious example, but even moves like including a 'developer guide' in the repo rather than a seperate file somewhere is a significant improvement.

- Manually written documentation will drift: This means you need capacity to maintain it. You're much better off manually documenting a few high level design choices and keeping it up to date, than trying to capture everything and it becoming inaccurate.

- Developer experience reduces the need for documentation: If you can automate stuff as much as possible, including offloading things to a type system etc to rule out mistakes, you'll reduce the amount new developers need to know to be effective, and therefore the ammount that has to be extensively documented. People are better learners when they do it slowly as they need than when they get given everything in one huge document to read.

Re: Ask HN: How To: Internal Documentation?

#17

Post by jakjak123 »

Realistically, my advice is. Document as little as possible. Build processes into your tools so it can be tested and repeated. Documentation that can get outdated, will be outdated and even worse be wrong. And, for example APIs can be organized in a way that documentation can be automated, so its never wrong or outdated, by choosing to use API contract first, like Protobuf or implementing via OpenAPI specifications. If you are implementing a specification of some kind, keep a copy of the specification version you have implemented checked in with the code.

Other things I have seen is f.ex. code that implements a business process, also can output itself as a Graphviz drawing, describing the parts of its own structure.

Re: Ask HN: How To: Internal Documentation?

#18

Post by nvarsj »

README.md/DEVELOPER.md in the project repo which details how to set up and get things running. That has the highest bang for buck in my experience, and is usually kept up to date as it's right next to the code and easy to update.

Re: Ask HN: How To: Internal Documentation?

#19

Post by nmat »

codingdave wrote: post #10
nmat wrote: post #5

I strongly believe that proactively keep documentation up to date is not worth the effort. Here is what I recommend in my teams: - There’s an onboarding guide that is usually only updated when new people onboard. If something is not right they raise it and their onboarding partner fixes it. - When someone shares a technical document/RFC we add it to a central repository with a creation date on it. These are point in…

Funny, I just posted the exact opposite. And find that everyone reads my docs, and comes back to them frequently as they work in different areas of the codebase. Of course, we are a remote team who swaps people in and out often, so onboarding is not a one-time event where you have partners to hold your hand. If you really only onboard once and don't have a fast-growing team, I could see where the needs would not matc…

And do you go back and update all documents whenever something changes? If you’re swapping people around every month I agree that you must keep everything written down, happens a lot in projects that bring consultants in. But if you have a core team of people and you get 2-3 new people per year then you should be more relaxed about it.

Re: Ask HN: How To: Internal Documentation?

#20

Post by adisin3 »

"writing, reading, and maintaining documentation could get much smoother" - something we've been trying to do over at Komment. CI/CD approach to docs so they don't drift from code and a single portal where all the generated docs are available for anyone in the company. Check it out https://www.komment.ai
Post reply on HN