documentation-framework
redux
documentation-framework | redux | |
---|---|---|
54 | 269 | |
89 | 60,537 | |
- | 0.1% | |
5.2 | 8.8 | |
about 1 month ago | 5 days ago | |
Python | TypeScript | |
- | MIT License |
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.
documentation-framework
- How-To Document: The Documentation System
-
Ask HN: How do you organize software documentation at work?
I forget the terminology, but there's a good "grid" breakdown of documentation types (I think this one: https://documentation.divio.com ) that I've simplified a bit for the internal documentation I'm involved with.
* README, HOWTO, INFO, PROJECT, DESIGN, NOTES, FAQ
When I pull down a `git` repo, I read the `README.md` (of course). I make my own `NOTES.md` (eg: `.gitignore`'d) of what commands, environment variables, useful blog posts, search results, whatever. Rarely do I share or encourage sharing of `NOTES.md` wholesale, but it's helpful to be able to pull out a few snippets or re-orient myself when coming back to that software/project.
Then, other documents get prefixed with "HOWTO-Do-Some-Specific-Thing.md", or "INFO-Some-Particular-Component.md".
"PROJECT-...", and "DESIGN-..." are "dangerous" ones in that they can quickly fall out of date, but they can be very useful while they're being actively managed. I guess personally I've started making sure to include dates or "eras" in the title, eg: "PROJECT-[2024-Feb]-Add-Foo-Support.md" or "DESIGN-[2024-02-14]-...". Stuff that's outlived its usefulness can probably be moved to an `ARCHIVE/...` in case you need it later, but keep it out of the way from confusing newcomers 1-3 years from now.
"FAQ-..." almost never comes into play (hopefully) b/c it should mostly get absorbed into "HOWTO-..." or product improvements, and few products seem to rise to the level of needing FREQUENTLY asked questions. Ideally FAQ's would "go away" with work on the product or other documentation, but I've had some success with it as like sales-oriented (and ideally: sales-managed) FAQ / Canned Customer Response learnings.
Putting it all together you get something like:
* README.md
-
Mastering JavaScript: Essential Topics to Crack Your Frontend Interview
Resource: Documentation Best Practices - GitBook
-
Duty to Document
I would not suggest people to follow this in 2024 if they are building any system of non-trivial scope and expect it to be adopted by others who are not required to adopt it.
Back in 2017, I compared "code as documentation" to being dropped into on the street of an unfamiliar city, while a good documentation can serve as a map of the city. [1]
Nearly all recent successful efforts for large new systems understand the value of both high-level overviews and detailed examples / onboarding materials to make adoption easier. When solutions to a certain problem are abundant, people do not need to settle for options that do not have great supporting documentation of the four primary kinds. [2]
[1] https://speakerdeck.com/maxvt/i-got-a-lot-of-problems-with-i...
[2] https://documentation.divio.com/
-
Guidance on man pages for the GNU project is wild
In the whole spectrum of documentation, man pages were designed to cater for a very specific need: information-oriented reference data. Check https://documentation.divio.com/ for a wonderful classification of documentation into four quadrants: reference, explanations, tutorials, and how-to guides. On the other hand, one can write info files for any of the use cases. That does not make info format inherently better or worse than man pages.
During the years, there have been many attempts to bridge the format gap, and convert texts from one representation to another. One of the most ambitious ones was in Tkman, a man viewer built on then Tcl/Tk system. Its really interesting part was the inclusion of rman, or RosettaMan, a converter of text to a somewhat abstract representation that could then be viewed via a GUI.
I personally look for well-crafted man pages as a sign of quality in software and try to provide them in everything I develop. I admit that I don't often find the time or motivation to write non-reference documentation (like tutorials).
-
Who has the best documentation you’ve seen or like in 2023
I ran into the divio documentation guide recently that seems to have some awesome "how to write docs" docs
-
Finally, a guide for Node.js and TypeScript and ESM that works
https://documentation.divio.com/ is a good overview of the "four types of documentation" paradigm: tutorials, how-to guides, explanations, and reference have to all exist.
One of my major gripes with the JS/TS ecosystem is that "explanations" are sorely lacking. See https://www.typescriptlang.org/tsconfig for the relevant documentation for tsconfig files. Tutorials are on the page, how-to guides abound on the wider internet (like the OP), and the linked TSConfig Reference and JSON Schema (used in code completion in IDEs) are together absolutely massive.
But an explanation is missing! There is no official documentation about how different options interact to say: as I'm walking a file tree as the Typescript compiler, this is how I will interpret a certain file I encounter, what will be outputted, and how that will be interpreted by bundlers and browsers, especially in an ESM world.
https://medium.com/extra-credit-by-guild/tsconfig-json-demys... is in the right direction, but outdated as ESM has become much more popular in the past 3 years, and still organized by option (so it's already somewhat in the "reference" world).
IMO even independent of documentation, the industry's move to ESM is problematic: https://gist.github.com/joepie91/bca2fda868c1e8b2c2caf76af7d... describes many of the issues. But they're certainly exacerbated by good explanation-style documentation that helps people understand how ESM works under the hood!
-
Ask HN: How do you document engineering efforts?
I really like the system detailed here: https://documentation.divio.com/. That's targeted more towards externally visible docs, but IMO adapts pretty well as for internal resources too.
- YOLO-Driven Development Manifesto
- Documentation
redux
-
A Comprehensive Guide to React State Management
Redux
-
Full Stack Web Development Concept map
redux - Redux is a key tool used in managing state across an application. This can be used with any web technology including React, Vue and Angular docs
-
State Management Nx React Native/Expo Apps with TanStack Query and Redux
Redux is a client-state library.
- Redux 101
-
The 20 most used React libraries
react-redux: A powerhouse for efficient state management and data flow control. Learn more
-
React State Management in 2024
Reducer-based: requires dispatching actions to update a big centralised state, often called a “single source of truth”. In this group, we have Redux and Zustand.
- Redux Toolkit 2.0: new features, faster perf, smaller bundle sizes (plus major versions for all Redux family packages!)
-
Redux Toolkit 2.0: new features, faster perf, smaller bundle sizes, and more
I am _thrilled_ to announce that:
Redux Toolkit 2.0 is LIVE!!!
- https://github.com/reduxjs/redux-toolkit/releases/tag/v2.0.0
This major version has new features, faster perf, smaller bundle size, and removes deprecated options.
It's accompanied by majors for all our Redux family packages
## RTK 2.0:
- a new `combineSlices` method for lazy-loading reducers - Updates to `createSlice` to include a `selectors` field and allow defining thunks inside
- Immer 10 w/ faster updates
- Removal of deprecated options
See the migration guide:
- https://redux.js.org/usage/migrations/migrating-rtk-2
All of the Redux libraries now have modernized packaging with full ESM/CJS compat. They also ship modern JS (no transpiling for IE11), which means smaller bundle sizes.
We've also done byte-shaving work to shrink the bundles (extracting error messages, de-duping imports)
## Redux core 5.0:
- The TS conversion we did in 2019!
- Action types _must_ be strings
- `UnknownAction` as the default action type
- Better preloaded state types
- Internal subscription improvements
- Still marks `createStore` as deprecated!
- https://github.com/reduxjs/redux/releases/tag/v5.0.0
## React-Redux 9.0:
- *Now requires React 18 and RTK 2.0 / Redux 5.0*
-
HTML Data Attributes: One of the Original State Management Libraries
DEV is a Rails monolith, which uses Preact in the front-end using islands architecture. The reason why I mention all this is that it's not a full-stack JavaScript application, and there is no state management library like Redux or Zustand in use. The data store, for the most part on the front end, is all data attributes.
-
Blogged Answers: My Experience Modernizing Packages to ESM
Oh hey, that's my post!
(yes I spend too much time refreshing HN :) )
FWIW I did end up with a packaging combination that seems to work sufficiently. I never did fix the "FalseCJS" issue that `are-the-types-wrong` is detecting. I played with double-emitting TS typedefs, and the `tsup` tool _does_ actually have support for that now (added by Andrew Branch from the TS team). So it might be more feasible now. But ultimately I decided I was tired of messing with packaging setup and that what I've got is good enough. (hopefully)
We're actually about to launch Redux Toolkit 2.0 and Redux 5.0 this week, assuming the last couple pieces come together. Here's the latest RCs - you can see the current `package.json` files in there:
- https://github.com/reduxjs/redux-toolkit/releases/tag/v2.0.0...
- https://github.com/reduxjs/redux/releases/tag/v5.0.0-rc.1
What are some alternatives?
diataxis-documentation-framework - A systematic approach to creating better documentation.
zustand - 🐻 Bear necessities for state management in React
pgf - A Portable Graphic Format for TeX
remix - Build Better Websites. Create modern, resilient user experiences with web fundamentals.
diagrams - :art: Diagram as Code for prototyping cloud system architectures
SWR - React Hooks for Data Fetching
awesome-writing - An awesome list of information to help developers write better, kinder, more helpful documentation and learning materials
valtio - 💊 Valtio makes proxy-state simple for React and Vanilla
boost - cmake based plugable static compiled boost library
swift-composable-architecture - A library for building applications in a consistent and understandable way, with composition, testing, and ergonomics in mind.
verifica - Verifica is Ruby's most scalable authorization solution
react-query - 🤖 Powerful asynchronous state management, server-state utilities and data fetching for TS/JS, React, Solid, Svelte and Vue. [Moved to: https://github.com/TanStack/query]