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

31–40 of 53 posts

Re: Ask HN: How To: Internal Documentation?

#31

Post by samayylmao »

jakjak123 wrote: post #17

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

+1 for protobuf/open-api.

My team has been using swashbuckle in the dotnet API ecosystem which generates an open-api document based on your code, commemts and c# attributes (for the things it can't infer from the former). The documentation and code have a symbiotic relationship.

Re: Ask HN: How To: Internal Documentation?

#32

Post by crayola »

That's the challenge we at Komment (komment.ai) are taking on -- providing tools to maintain high-quality, up-to-date code documentation. We enable developers to spend more time developing, and less time documenting or figuring out what undocumented code does :-)

Re: Ask HN: How To: Internal Documentation?

#33

Post by bogle »

- readme at the root of each of application with keeping it up to date part of each relevant change. Something perhaps to consider in peer reviews.

- onboarding checklist with the new person now responsible for the checklist so when the next person needs it they can take them through it.

- mentoring with real contact between the new person and the mentor so they engage in shadowing and pairing.

- wikis are generally pretty poor, partly as they are external to the daily work, partly because nobody is made responsible. Could you delete it?

Of these I consider the README to be the most important. Imagine you are an open source application and you want to encourage others to improve your code. How would you do that? Add clear instructions on how to get it working on every platform? Include diagrams, made with simple, free tooling like Mermaid and drawio? Describe architectural decisions?

Re: Ask HN: How To: Internal Documentation?

#34

Post by crayola »

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.

Fully agree -- documentation as markdown committed alongside the code (and processes to ensure that it is kept up-to-date, discoverable and browsable) is the best way to avoid docs going stale or abandonned.

Re: Ask HN: How To: Internal Documentation?

#35

Post by saruberoz »

+1 for this

I agree with you, In the world where information is overflowing, and communication is async, documentation is a great way to share knowledge But the hard thing about documentation is updating it, since it keep getting outdated. What we did as a team is we discuss and agree documentation should be made as part of our OKR, add doc as part of our process, and where we should put it; in hope of making it easier to share knowledge for older codebase, new joiners, or other team.

We use inline doc for engineering, and all other usually we use gdrive for detailed source of truth and for the summary we use https://getoutline.com/

Re: Ask HN: How To: Internal Documentation?

#36

Post by quesera »

acron0 wrote: post #23
jakjak123 wrote: post #17

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

What does "f.ex." mean here? Is it equivalent to "e.g."?

I believe it's something along the lines of "flagrant excision" (of established language conventions).

The resultant confusion from such communication innovations may be justifiable in service to a larger goal, e.g. making a clean cultural break from ancient lion-torturing Latin speakers.

Be the change you want to see. Et cetera, et alii.

Re: Ask HN: How To: Internal Documentation?

#37

Post by hiAndrewQuinn »

acron0 wrote: post #23
jakjak123 wrote: post #17

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

What does "f.ex." mean here? Is it equivalent to "e.g."?

"For example." It's a favorite phrase of the various Polish devs I've known, for some reason.

I like it! It looks fun and a little mischievous. I hope someday we start using fx in the same places we use ie or eg.

EDIT: My beautiful Finnish wife informs me t.ex. is also used in Swedish in a very similar way, till exempel or something like that. So maybe it's a Northern European thing too?

Re: Ask HN: How To: Internal Documentation?

#38

Post by hiAndrewQuinn »

crayola wrote: post #34
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.

Fully agree -- documentation as markdown committed alongside the code (and processes to ensure that it is kept up-to-date, discoverable and browsable) is the best way to avoid docs going stale or abandonned.

You can go all the way and make a Hugo website out of those Markdown docs pretty easily too. If anyone wants help doing this, feel free to drop me a line!

Re: Ask HN: How To: Internal Documentation?

#39

Post by codingdave »

nmat wrote: post #19
codingdave wrote: post #10

Earlier quoted context omitted.

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.

Yep, we do. It is part of the process just like testing. For the most part, it is not painful - most features are variations on existing patterns, and don't need updates. When we do code up a new pattern, we update docs.

And you are correct - we use consultants on the team, and hire in gig workers for small tasks on a regular basis. When I worked on a small core team without much churn, I did not do any of this.

Re: Ask HN: How To: Internal Documentation?

#40

Post by amonon »

koliber wrote: post #28

Most companies don’t have a problem with too little documentation. Instead, the documentation is hard to find when needed. I’m a documentarian and this is one of my favorite topics. My go to is creating a wiki for the team. The wiki is organized into hubs. There is a hub for each team. There is a hub for each topic such as security, new employee onboarding, etc. There might be a hub for each bigger project. A hub con…

How do you handle the discovery/relevance issue in a documentation base that is already several years old?
Post reply on HN