News for hackers. Stuff that matters.
Re:Ask HN: How To: Internal Documentation? by jakjak123 on Sunday September 01, 2024 @07:48AM (#41416129)
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? by acron0 on Sunday September 01, 2024 @08:12AM (#41416309)
What does "f.ex." mean here? Is it equivalent to "e.g."?
Re:Ask HN: How To: Internal Documentation? by Y_Y on Sunday September 01, 2024 @08:20AM (#41416366)
Foreign exchange
Re:Ask HN: How To: Internal Documentation? by techn00 on Sunday September 01, 2024 @08:17AM (#41416342)
for example?
Re:Ask HN: How To: Internal Documentation? by quesera on Sunday September 01, 2024 @09:31AM (#41416847)
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? by hiAndrewQuinn on Sunday September 01, 2024 @10:03AM (#41417059)
"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? by samayylmao on Sunday September 01, 2024 @08:34AM (#41416488)
+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.