mirror of
https://github.com/NixOS/nix.dev.git
synced 2024-10-18 14:32:43 -04:00
remove learning journey working group (#776)
- move tutorial process into the contribution guide - move documentation survey in the maintainers directory
This commit is contained in:
Valentin Gagarin
GitHub
parent
3a52c0ac05
commit
3373822a7b
|
|
@ -24,9 +24,6 @@ The team’s reason to exist is to make that principle discoverable and reproduc
|
|||
|
||||
The team member list is maintained on the [Nix community documentation team page](https://nixos.org/community/teams/documentation).
|
||||
|
||||
## Working Groups
|
||||
- [Learning Journey](working_groups/learning_journey/README.md)
|
||||
|
||||
## Responsibilities
|
||||
|
||||
### Team
|
||||
|
|
|
|||
|
|
@ -1,87 +0,0 @@
|
|||
# Learning Journey Working Group
|
||||
|
||||
## Goals
|
||||
The primary goal of the Learning Journey Working Group is to provide Nix users with adequate resources to learn Nix on their own. This means that it is the job of the WG to determine the most effective methods for teaching Nix, including:
|
||||
- Ensuring that adequate documentation exists
|
||||
- Ensuring that the documentation is structured in an intuitive way
|
||||
- Ensuring that the documentation is discoverable
|
||||
- Ensuring that the documentation meets a minimum standard of quality
|
||||
- Establishing guidelines for contributions
|
||||
|
||||
By extension the WG will be responsible for practical aspects such as:
|
||||
- Some portion of the structure of `nix.dev` so that documentation is discoverable and organized intuitively
|
||||
- Ensuring that bare minimum authoring tools exist to keep the barrier low for contributions from new contributors
|
||||
|
||||
## Membership
|
||||
Leads: @zmitchell
|
||||
|
||||
Members:
|
||||
- @infinisil
|
||||
- @henrik-ch
|
||||
- @erooke
|
||||
- @asymmetric
|
||||
|
||||
Membership is open to anyone that wants to contribute.
|
||||
|
||||
## Meetings
|
||||
Meetings will be held every week to ensure that progress can be made between meetings.
|
||||
|
||||
## Immediate projects
|
||||
### Decide on documentation structure
|
||||
This project will decide on a high level structure for the documentation so that contributors know the audience they are speaking to and where their contributions fit into the Nix documentation landscape.
|
||||
|
||||
The documentation will follow the [Diataxis](https://diataxis.fr) framework to the degree that it makes sense. This project will produce a proposal to be submitted to the Documentation Team.
|
||||
|
||||
The first draft of this structure is as follows:
|
||||
- Tutorials
|
||||
- Installation of Nix
|
||||
- Walking a user through their first derivation
|
||||
- Packaging an existing project for Nix for the first time
|
||||
- How-To
|
||||
- Packaging for specific languages
|
||||
- Packaging idioms
|
||||
- `callPackage`, "import from derivation", "fixed output derivation", etc
|
||||
- Day-to-day development and workflows
|
||||
- Integration with IDEs/editors
|
||||
- Nix in CI
|
||||
- Nix and NixOS deployments
|
||||
- Building containers
|
||||
- Rollbacks
|
||||
- Contributing in various ways
|
||||
- Explanation
|
||||
- Concepts
|
||||
- What is a derivation?
|
||||
- Cross-compilation as a first-class citizen
|
||||
- Where to put your dependencies (`buildInputs`, `nativeBuildInputs`, etc)
|
||||
- The Nix Store and the database
|
||||
- Channels, profiles, etc
|
||||
- Overlays, overrides, `follows`
|
||||
- Reference
|
||||
- Command reference
|
||||
- How store paths are computed
|
||||
- Build phases
|
||||
- How derivations work
|
||||
- Nix language reference
|
||||
- Flake schema
|
||||
|
||||
### Set standards for documentation pages
|
||||
In order to provide a level of consistent quality for the documentation, we should decide on the bare minimum standards for documentation pages.
|
||||
|
||||
Examples:
|
||||
- Pages should have a table of contents
|
||||
- Pages should refrain from first person voice
|
||||
- Decide how/whether different documentation sections should be handled differently (e.g. tutorial vs reference material)
|
||||
- etc
|
||||
|
||||
### Establish tooling and workflow
|
||||
We should have tooling that supports authors and enables them to contribute to the documentation with minimal boilerplate.
|
||||
|
||||
Examples:
|
||||
- Macros or snippets to insert callouts ("Note:", "Warning:", etc)
|
||||
- etc
|
||||
|
||||
## Long term projects
|
||||
### Migrate existing documentation
|
||||
There is a large body of existing documentation that should not be discounted. We should use the existing documentation to bootstrap the new, reorganized documentation.
|
||||
|
||||
Prior art: [Nix Book - Resources](https://github.com/NixOS/nix-book/blob/main/resources.md)
|
||||
|
|
@ -1,70 +0,0 @@
|
|||
# Sharing dependencies between `default.nix` and `shell.nix`
|
||||
|
||||
## Assumptions
|
||||
- The reader has seen a derivation before.
|
||||
- The reader understands that builders (also referred to as "build helpers") come from `nixpkgs`.
|
||||
- The reader knows what a declarative shell environment is.
|
||||
|
||||
## Activity
|
||||
|
||||
<!-- What is the activity you're going to walk the reader through. -->
|
||||
- Start with a `default.nix` that builds a project.
|
||||
- Show the reader how to share dependencies between a build and a shell environment.
|
||||
|
||||
## Purpose
|
||||
|
||||
<!-- What is the reader supposed to gain from reading this? -->
|
||||
- Show the reader how to set up a development environment.
|
||||
- Show the reader how not to repeat themselves.
|
||||
- Show the reader how to import one Nix file into another.
|
||||
|
||||
## Steps
|
||||
|
||||
<!-- Prepare a bulleted outline of how you're going to walk the reader through this activity. -->
|
||||
<!-- Be specific about how you're going to teach this activity, we want to catch any pitfalls before the writing phase. -->
|
||||
- Begin with a `default.nix` that builds an application.
|
||||
- Show the reader that the application builds.
|
||||
- Present a scenario that prompts for a better working environment.
|
||||
- We'd like to include modern development tooling like a test runner, linter, and formatter.
|
||||
- Demonstrate that in order to bring those tools into our environment with the current `default.nix` those packages would also be included in the build even though they aren't necessary to build our application.
|
||||
- (Optional) Add the packages to `propagatedBuildInputs` and show that they're included in the closure.
|
||||
- Create a `shell.nix` to separate build dependencies from development dependencies.
|
||||
- Duplicate dependencies from `default.nix` so that you can still perform the build in `shell.nix`.
|
||||
- Add the development tools to `shell.nix` so that the reader has access to the during development.
|
||||
- Demonstrate that you can still build the application.
|
||||
- Explain that having to repeat yourself in both files is less than ideal and that you could easily forget to add a dependency to one file or the other.
|
||||
- Explain that one solution is to repeat yourself, but that it isn't ideal and you should avoid it.
|
||||
- Explain that you could:
|
||||
- Create a separate `shell.nix`
|
||||
- Duplicate the build dependencies
|
||||
- Then include the development tools
|
||||
- Explain that the drawback is that the build dependencies could fall out of sync between `default.nix` and `shell.nix` by mistake.
|
||||
- Introduce `mkShell.inputsFrom` as a way to prevent duplication.
|
||||
- Explain that `inputsFrom` extracts `input` attributes from the supplied derivation and passes them to `mkShell`.
|
||||
- Demonstrate how to import the `default.nix` expression into `shell.nix` and use its inputs.
|
||||
- Demonstrate how to put the `mkShell` call in `default.nix`.
|
||||
- Explain that defining the shell this way helps to keep more of the functionality in `default.nix`, leaving `shell.nix` to be the necessary glue to allow `nix-shell` to use the shell we've defined.
|
||||
|
||||
In the end you should end up with files that look like this (examples are Python just for demonstration purposes here):
|
||||
```
|
||||
# default.nix
|
||||
let
|
||||
myPackage = python3Packages.buildPythonApplication {
|
||||
propagatedBuildInputs = [
|
||||
python3Packages.flask
|
||||
];
|
||||
};
|
||||
in myPackage // {
|
||||
shell = mkShell {
|
||||
inputsFrom = [
|
||||
myPackage
|
||||
];
|
||||
buildInputs = [
|
||||
curl
|
||||
];
|
||||
};
|
||||
}
|
||||
|
||||
# shell.nix
|
||||
(import ./default.nix).shell
|
||||
```
|
||||
|
|
@ -1,14 +0,0 @@
|
|||
# TITLE
|
||||
|
||||
## Activity
|
||||
|
||||
<!-- What is the activity you're going to walk the reader through. -->
|
||||
|
||||
## Purpose
|
||||
|
||||
<!-- What is the reader supposed to gain from reading this? -->
|
||||
|
||||
## Steps
|
||||
|
||||
<!-- Prepare a bulleted outline of how you're going to walk the reader through this activity. -->
|
||||
<!-- Be specific about how you're going to teach this activity, we want to catch any pitfalls before the writing phase. -->
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
# Tutorial Workflow
|
||||
|
||||
This document describes the recommended workflow when creating tutorials for the learning journey tutorial series.
|
||||
|
||||
## Writing process
|
||||
### Pick a tutorial
|
||||
There are [tracking issues][tracking_issues] for tutorials that the working group has decided should exist as part of the tutorial series.
|
||||
Pick an issue that covers a topic that you're either knowledgeable about or have a particular interest in, then comment on the issue indicating your interest in working on the tutorial.
|
||||
|
||||
The tracking issue will contain status information such as whether PRs have been submitted to create an outline or a draft of the article or whether someone else has already started work on the tutorial.
|
||||
Make sure to read the issue fully to ensure that you don't duplicate work that someone else is already doing!
|
||||
|
||||
[tracking_issues]: https://github.com/NixOS/nix.dev/issues?q=is%3Aissue+is%3Aopen+label%3Atracking+label%3A%22learning+journey%22
|
||||
|
||||
### Submit an outline PR
|
||||
Submit a PR with an outline of the tutorial using the [tutorial outline template][tutorial_outline_template], placing the outline in the [tutorial outlines directory][outlines_dir].
|
||||
The outline will go through a review process to ensure that the material is satisfactory and is detailed enough that any other contributor could pick it up and work on it.
|
||||
In particular, the tutorial outline should:
|
||||
|
||||
- Be a tutorial as defined in the [Diataxis][diataxis_tutorial] framework.
|
||||
- Clearly state the prerequisite knowledge.
|
||||
- Have a well-defined scope and learning objective.
|
||||
|
||||
[tutorial_outline_template]: ./tutorial-outlines/template.md
|
||||
[outlines_dir]: ./tutorial-outlines/
|
||||
[diataxis_tutorial]: https://diataxis.fr/tutorials/
|
||||
|
||||
### Submit a draft PR
|
||||
Once the outline PR has been merged, work can begin on a draft of the tutorial.
|
||||
Follow the [how to write a tutorial][tutorial_guide] guide and adhere to the [style guide][style_guide] while writing to follow conventions used throughout the rest of the site's documentation and make review less labor intensive for maintainers.
|
||||
|
||||
Submit a PR with a draft of the tutorial using the [tutorial template][tutorial_template], placing the draft in the `source/tutorials/learning-journey`.
|
||||
At this point the draft will receive editorial review from @zmitchell and technical review from @infinisil or @roberth.
|
||||
|
||||
The draft will become an official tutorial if it passes review.
|
||||
|
||||
[tutorial_template]: ../../../source/tutorials/learning-journey/template.md
|
||||
[tutorial_guide]: ../../../source/contributing/writing-a-tutorial.md
|
||||
[style_guide]: ../../../source/contributing/style-guide.md
|
||||
|
|
@ -87,3 +87,25 @@ We recommend making an explicit separation of practical from theoretical learnin
|
|||
|
||||
External resources should have a summary to set expectations, ideally including reading time.
|
||||
Blog posts should have their original title in the link, and `(<author>, <year>)`: give authors credit, give readers an idea of how up to date the information is.
|
||||
|
||||
## Process
|
||||
|
||||
### Pick a topic
|
||||
|
||||
There are [tracking issues] for tutorials that the working group has decided should exist as part of the tutorial series.
|
||||
Pick an issue that covers a topic that you're either knowledgeable about or have a particular interest in, then comment on the issue indicating your interest in working on the tutorial.
|
||||
|
||||
The tracking issue will contain status information such as whether PRs have been submitted to create an outline or a draft of the article or whether someone else has already started work on the tutorial.
|
||||
Make sure to read the issue fully to ensure that you don't duplicate work that someone else is already doing!
|
||||
|
||||
[tracking issues]: https://github.com/NixOS/nix.dev/issues?q=is%3Aissue+is%3Aopen+label%3Atracking+label%3A%22learning+journey%22
|
||||
|
||||
### Submit an pull request with an outline
|
||||
|
||||
Submit a pull request with an outline of the tutorial following the above structure and containing bullet points on each section's content.
|
||||
A review will ensure the work is going in the right direction in terms of learning objectives and technical details.
|
||||
|
||||
### Expand on the outline
|
||||
|
||||
Elaborate the contents of the tutorial following your outline and the [](style-guide).
|
||||
In a final review will check that everything is technically correct.
|
||||
|
|
|
|||
Loading…
Reference in a new issue