News for hackers. Stuff that matters.

mrmb

Re:Ask HN: How do you organize software documentation at work? on Wednesday February 14, 2024 @10:27AM (#39370914)
Location: Separate Documentation repository in a GitLab group project. That way you have history, notes, membership, ownership, and processes (templates, merge permissions, reviewers)! This can also be included as a submodule in your software repo. And can be used to read/edit by devs in their chosen IDE, or R/W on GitLab via html, or can generate static html documentation via pipelines. Oh, and you can build pipelines to generate html outputs for different use cases, and perform checks, run scripts, etc.

Framework: Choose a framework, like Arc42 for general layout as a good starting point. Remember you have company, quality, project, program, product, process, user, internal how-to's, etc. documentation types not just... user-guides and systems-architecture..so this will be dependent on your org/product. Go for MVP and 80-20.

Plan: Write a plan as part of the documentation that details all of these facets and rules so all contributors understand it.

Formats: drawio.svg for complex diagrams, mermaid for simple diagrams or if important to change manage like code, asciidoc for complex documents, markdown for most/simpler docs. Tables in csv or asciidoc. Images in svg, or png. Everything aforementioned renders on GitLab.

Other rules: Automate everything possible to reduce [manual] documentation. Use text/code vs proprietary formats.

You can get more and more complex with the tech writers, dev, ops, systems, all under one roof and coordinating documentation and pipeline scripting.

Next up on the playlist, plastic beach (Gorillaz, 2010)
Re:The Minecraft Generation on Friday April 15, 2016 @05:28PM (#11507751)
> To play, you’ll need a computer with Minecraft and a child who’s familiar with the game.

Hilarious, and true. Oh, I hope someday to be asked how one plays Minecraft...

Re:Code that will break in Python 4 on Tuesday January 12, 2016 @11:25AM (#10888278)
From Guido: he expects "Python 4.0 will merely be "the release that comes after Python 3.9". That's it. No profound changes to the language, no major backwards compatibility breaks"

http://www.curiousefficiency.org/posts/2014/08/python-4000.h...

Would be nice if it was simply 3.10 not 4.0, as there's much discussion on that too.