hitchstory
diataxis-documentation-framework
hitchstory | diataxis-documentation-framework | |
---|---|---|
23 | 72 | |
83 | 710 | |
- | - | |
9.1 | 8.7 | |
16 days ago | about 1 month ago | |
Python | HTML | |
GNU General Public License v3.0 or later | GNU General Public License v3.0 or later |
Stars - the number of stars that a project has on GitHub. Growth - month over month growth in stars.
Activity is a relative number indicating how actively a project is being developed. Recent commits have higher weight than older ones.
For example, an activity of 9.0 indicates that a project is amongst the top 10% of the most actively developed projects that we are tracking.
hitchstory
- Hitchstory – Type-safe StrictYAML Python integration testing framework
-
Winner of the SF Mistral AI Hackathon: Automated Test Driven Prompting
I built something like this too:
https://github.com/hitchdev/hitchstory/blob/master/examples%...
- Prompt Engineering Testing Framework
-
Non-code contributions are the secret to open source success
I took the same approach to "docs are tests and tests are docs" with integration testing when I created this library: https://github.com/hitchdev/hitchstory
I realized at some point that a test and a how-to guide can and should actually be the same thing - not just for doctests, but for every kind of test.
It's not only 2x quicker to combine writing a test with writing docs, the test part and the docs part reinforce each other:
* Tests are more easily understandable when you attach written context intended for human consumption.
* Docs are better if they come attached to a guarantee that they're valid, not out of date and not missing crucial details.
* TDD is better if how-to docs are created as a side effect.
-
Ask HN: Are there any LLM projects for creating integration tests?
I have created a project for easily writing this type of test with YAML:
https://github.com/hitchdev/hitchstory
I dont think that this type of task is really appropriate for an LLM though. It is better to use hard abstractions for the truly deterministic stuff and for other stuff where you may need to do subtle trade offs (e.g. choosing a selector for the search bar) an LLM will generally do a bad job.
-
Should you add screenshots to documentation?
For those interested in the concept of having permanently up-to-date documentation with screenshots I built this testing framework based upon the idea that good documentation can be a autogenerated artefact of good tests:
https://github.com/hitchdev/hitchstory
-
How to add documentation to your product life cycle
I don't like gherkin. It's it has very awkward syntax, it's not type safe, it's very verbose, it has no ability to abstract scenarios and rather than being a source for generating the documentation it tries to be the documentation.
Nonetheless, there is a small number of projects where they either work around this or it doesn't matter as much. I find that most people that apply gherkin to their projects find it doesn't work - usually for one of the above reasons.
I built https://github.com/hitchdev/hitchstory as an alternative that has straightforward syntax (YAML), very strict type safety (StrictYAML), low verbosity, and is explicitly designed as a source for generating documentation rather than trying to be the documentation.
-
Beyond OpenAPI
I built this because I had the same idea: https://github.com/hitchdev/hitchstory
If the specification can be tested and used to generate docs and can be rewritten based upon program output then the maintenance cost for producing docs like these plunges.
-
Optimizing Postgres's Autovacuum for High-Churn Tables
-c fsync=off -c synchronous_commit=off -c full_page_writes=off
I got the answer from Karen Jex at Djangocon 2023.
I used it to build some integration tests which exhibit best practices: https://github.com/hitchdev/hitchstory/tree/master/examples/...
I considered using tmpfs but I wanted to cache the entire database volume and couldnt figure out how to do that with podman.
-
Elixir Livebook is a secret weapon for documentation
This is incredible work.
To anyone curious, I highly recommend:
- https://hitchdev.com/hitchstory/approach/
- https://hitchdev.com/hitchstory/why-not/
From the overall RDD/BDD type home page:
- https://hitchdev.com/hitchstory/
The entire product site is a thing of richly informative beauty.
---
My only question was whether the generated 'docs' snippets would add value over just reading the story in your DASL. Any markdown site generator (such as the chosen Material for MKDocs) can just embed the ```yaml anyway. But then I realized what was generating e.g. …
- https://hitchdev.com/hitchstory/using/engine/rewrite-story/
… and how superior that is to typical docs, especially typical docstring or swagger factories.
diataxis-documentation-framework
- How-To Document: The Documentation System
- Diátaxis
-
The IDEs we had 30 years ago and we lost
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
-
Lessons in Leadership Excellence
Create an organized repository for regularly updated documentation, making it easy to access important information.
- Docs Deserve More Respect
-
Nx Conf 2023 - Recap
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.
-
Beyond OpenAPI
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.
-
Where is the documentation for the text models
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.
-
The PostgreSQL Documentation and the Limitations of Community
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 Surprising Power of Documentation
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
What are some alternatives?
bumblebee - Pre-trained Neural Network models in Axon (+ 🤗 Models integration)
technical-writing - A collection of materials relating to technical writing
jsverify - Write powerful and concise tests. Property-based testing for JavaScript. Like QuickCheck.
documentation-framework - "The Grand Unified Theory of Documentation" (David Laing) - a popular and transformative documentation authoring framework
testy - test helpers for more meaningful, readable, and fluent tests
awesome-writing - An awesome list of information to help developers write better, kinder, more helpful documentation and learning materials
examples - Tests that rewrite themselves. Tests that rewrite your docs.
just - 🤖 Just a command runner
ospec - Noiseless testing framework
arc42.org-site - (jekyll-based) website for arc42.org - the template for communicating software architectures.
explorer - Series (one-dimensional) and dataframes (two-dimensional) for fast and elegant data exploration in Elixir
mark - Sync your markdown files with Confluence pages.