diataxis-documentation-framework VS just

Perhaps it could be restructured to separate out the howto from the explanation to serve the reader’s intended use at the time as described here: https://diataxis.fr

Create an organized repository for regularly updated documentation, making it easy to access important information.

Such integration capabilities really help push the developer productivity, whether that's in single-project workspaces or monorepos. Juri also dives deeper into efforts from the team to provide high quality educational content around Nx and its capabilities. The Nx docs have been restructured to follow the Diataxisframework, dividing content into into learning-, task-, understanding- and information-oriented sections.

I think people may be missing the core point of this article.

Anton has built a new thing, https://codapi.org/ - which provides a web component that makes it easy to embed interactive code snippets for HTTP APIs, Python code and more directly in pages of documentation.

This article demonstrates this new technology in the context of the https://diataxis.fr/ documentation framework, which recommends going beyond just straight API reference documentation and ensuring you cover tutorials, how-to guides and explanations as well.

I think this is really cool.

As much as possible on all facets, because that is what "documentation" means, and if you are a product manager who wasn't paying attention in product management 101 and need some guidance on what "documentation" is, try reading this first.

Related: Diátaxis - A systematic framework for technical documentation authoring [1]

"The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product.

Diátaxis identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. It derives its structure from the relationship between them.(...)"

[1] https://diataxis.fr/

the divio style docs concept got further refined by the creator with this - https://diataxis.fr/

mostly the same but some additional information for people who are interested

I don't like makefiles, but I've been enjoying justfiles: https://github.com/casey/just

I started using just [0] on my projects and have been very happy so far. It is very similar to make but focused on commands rather than build outputs.

Define your recipes and then you can compose them as needed.

[0] https://github.com/casey/just

just - https://github.com/casey/just

Welp there is absolute chaos in that thread -- guess it's not an April Fools joke.

I wonder if relying on CI for anything other than provisioning machines is a mistake -- maybe we should have never moved from doing things from local scripts written in $LANGUAGE.

That said, I'm probably biased since I'm a massive fan of things like `make` and more appropriately for the current age, `just`[0]

[0]: https://github.com/casey/just

> When a command has some cognitive requirements I create a script with some ${1:-default} values and I store them all in $PATH enabled local/bin

I would consider using just for this:

https://github.com/casey/just

Your coworker's experience is more principled: Make is a mediocre tool for executing commands. It wasn't ever designed for that. Although it is pretty common to see what you are mentioning in projects because it doesn't require installing a dependency.

For a repo where an easy to install (single binary) dependency is a non-issue, consider using just. [1] You get `just -l` where you can see all the command available, the ability to use different languages, and overall simpler command writing.

[1] https://github.com/casey/just

This is fantastic, but I'd say that this solution is somewhat in response to this open issue from 2019:

https://github.com/casey/just/issues/429

I really wish just was included as a package in distributions.

So far, I didn't work on new features at all but on stabilizing the ground for further development: 1. CMake lists and modules were rewritten a lot, now managing builds and their configurations is much lesser pain. 2. Brought in Justfile for regular tasks, and it's great, no less. 3. Linters, formatters, analyzers for almost all the code (except for Janet for now, as because of it being a niche and young technology, it didn't get enough attention yet). 4. ECS stub. Now runtime class doesn't look like a god object. 5. Started writing unit tests which didn't happen with my personal projects before and maybe indicates how serious am I about this one :D 6. Some of previously hardcoded data has been moved to INI files. Now, if I release the game in 10 years, and in 10 more years some eccentric person decides to make a variant of it, it will be slightly simpler.

i've grown to like this for my personal projects. https://github.com/casey/just