simple server client test #725
Conversation
olafklingt
force-pushed
the
server-client-test
branch
4 times, most recently
from
9a71d19
to
6129606
Compare
|
This is a very good idea. A tutorial should focus on the principle. But before we remove the example altogether, let's either move it to the manual where all examples are collected, or link to more third-party sources, so it's more likely for learners to find something that best matches their use case. |
Is the Manual the right place for such recipes? |
I'd say it depends how you frame it. If it's a pure example, it should be in the manuals. Having a small collection there would be good. A recipe would summarize the pattern and link to specific reference documentation for details, so it doesn't really need fully working examples. Given the introduction in the tutorial already shows the pattern, we may leave it at that for now and consider reproducing it in isolation in the recipes section for better discoverability later. Using the wiki as a low friction dumping ground for ideas is a good idea though. |
|
Ok I moved the example derived from @Gabriella439 's blog to the wiki. |
while section headings are good for linking, this is not very important here. the heading distract from the sequential structure, which the list exposes more clearly.
- use the same Nixpkgs release to avoid massive downloads - continue using `pkgs.nixosTest`; the new thing is completely undocumented - use a shorthand module; `lib` is not used - use an empty nginx config; commented-out code is confusing - move explanation of the test script to the end; use imperative - add instructions to run it
readers don't even need to think about it, as it's encoded in the pinned source. at best this would be a note to maintainers, but we should know that as well.
fricklerhandwerk
force-pushed
the
server-client-test
branch
from
2b59527
to
a2a706f
Compare
Deploy Preview
|
|
@olafklingt Thank you very much for the thorough research! Although the diff got quite large, in essence it's just polish. Each small change is documented (and hopefully well-enough explained) in the commit log. This is really a great piece of exposition to an extremely powerful feature. Once we get #701 in, it will also have its due place in the learning journey. I'd like to merge it as it is now, but a brief last check from the @NixOS/documentation-team won't hurt. If anything, both the pain to create this kind of tutorial as well as the shape of the result strongly indicate that we have to double down on reference documentation - as @Ericson2314 suggested again and again. And as @infinisil suggested recently, to make working on reference documentation easier we have to double down on cleaning up the implementation. |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-10-09-documentation-team-meeting-notes-85/34046/1 |
proposal to replace the complicated server client test with a simple test.
... unfortunately its so simple that one doesn't have to deal with network issues at all.