mirror of
https://github.com/nix-dot-dev/nix.dev.git
synced 2024-10-05 17:47:29 +03:00
update information flow diagram
we probably don't need it here in particular, but originally when the documentation team was new, it was useful to understand and communicate what's going on. it can probably stay here until we either find a better place or feel like it's in the way. until then, a small update for clarity and consistency.
This commit is contained in:
parent
46a7927691
commit
06e89b89d4
@ -1,66 +0,0 @@
|
||||
# How to contribute to documentation in the Nix ecosystem
|
||||
|
||||
If you want to help improving documentation, consider the following guidelines developed by the [Nix documentation team](./README.md).
|
||||
|
||||
Different audiences require different levels of sophistication, and both readers' and contributors' available time and expertise varies widely.
|
||||
|
||||
Use the following diagram to decide where to best put the results of your efforts, depending on how much time you can spend on refining them to get accepted.
|
||||
|
||||
The diagram shows a pipeline for contributions to learning materials and documentation.
|
||||
Arrows point towards
|
||||
|
||||
- decreasing rate of change
|
||||
- increasing public visibility
|
||||
- increasing amount of scrutiny.
|
||||
|
||||
Communication platforms are distinguished by mode of interaction:
|
||||
|
||||
Streams can be appended to:
|
||||
|
||||
- The amount of information in them grows without bounds.
|
||||
- Only recent items are relevant.
|
||||
|
||||
Artifacts can be changed:
|
||||
|
||||
- The amount of information in them is strictly bounded.
|
||||
- All items should be up to date.
|
||||
|
||||
```mermaid
|
||||
flowchart
|
||||
Matrix --> |filter| Discourse
|
||||
events[meetings and events] --> |report| Discourse
|
||||
external[external sources] --> |collect| Discourse
|
||||
Discourse --> |design| RFCs
|
||||
Discourse --> |change| code[source code]
|
||||
Discourse --> |learn| Wiki
|
||||
Wiki --> |refine| manuals --> |guide| dev[nix.dev] --> |overview| www[nixos.org]
|
||||
RFCs --> code --> |document| manuals
|
||||
subgraph stream
|
||||
Matrix
|
||||
events
|
||||
external
|
||||
Discourse
|
||||
RFCs
|
||||
end
|
||||
subgraph artifact
|
||||
Wiki
|
||||
code
|
||||
manuals
|
||||
dev
|
||||
www
|
||||
end
|
||||
```
|
||||
|
||||
## Contributing to this guide
|
||||
|
||||
Do you have suggestions how to ease contributing to documentation in the Nix ecosystem?
|
||||
Please open a pull request to update this document with your proposals.
|
||||
|
||||
## Links to this guide
|
||||
|
||||
In case this guide moves, the following documents link here and should be updated:
|
||||
|
||||
- [Discourse: Summer of Nix documentation stream](https://discourse.nixos.org/t/summer-of-nix-documentation-stream/20351)
|
||||
- [Discourse: How to contribute to documentation](https://discourse.nixos.org/t/how-to-contribute-to-documentation/21028)
|
||||
- [NixOS Wiki: Contributing to Nix documentation](https://nixos.wiki/wiki/Contributing_to_Nix_documentation)
|
||||
|
53
maintainers/information-flow.md
Normal file
53
maintainers/information-flow.md
Normal file
@ -0,0 +1,53 @@
|
||||
# Information flow in the Nix ecosystem
|
||||
|
||||
The diagram shows a simplified model of the information flow in the Nix ecosystem.
|
||||
Its purpose is to make dependencies of the documentation types more explicit.
|
||||
Note that it does not show issues and pull requests on GitHub, which host a wealth of ephemeral information.
|
||||
|
||||
Nodes are places or resources, edges denote an "informed by" relation, and edge labels are units of information.
|
||||
Read the example as "A is informed by X and placed in Y":
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
X --> |A| Y
|
||||
```
|
||||
|
||||
Information resources – communication platforms – are distinguished by mode of interaction:
|
||||
|
||||
*Streams* can be appended to:
|
||||
|
||||
- The amount of information in them grows without bounds.
|
||||
- Only recent items are relevant.
|
||||
|
||||
*Artifacts* can be changed:
|
||||
|
||||
- The amount of information in them is strictly bounded.
|
||||
- All items should be up to date.
|
||||
|
||||
```mermaid
|
||||
flowchart
|
||||
Matrix --> |summary| Discourse
|
||||
events[meetings and events] --> |meeting notes, report| Discourse
|
||||
external[external sources] --> |link| Discourse
|
||||
Discourse --> |draft| RFCs --> |implementation| code
|
||||
RFCs --> |explanation| docs
|
||||
code --> |reference| manuals --> |guide| docs[nix.dev]
|
||||
Discourse --> |tutorial| docs
|
||||
subgraph stream
|
||||
Matrix
|
||||
events
|
||||
external
|
||||
Discourse
|
||||
RFCs
|
||||
end
|
||||
subgraph artifact
|
||||
code
|
||||
manuals
|
||||
docs
|
||||
end
|
||||
```
|
||||
|
||||
Arrows point roughly towards
|
||||
|
||||
- decreasing rate of change
|
||||
- increasing public visibility
|
Loading…
Reference in New Issue
Block a user