begin guide on how-to guides #977
Conversation
| @@ -0,0 +1,46 @@ | |||
| # How to write a how-to guide | |||
|
|
|||
| This is a guide to writing how-to guides on Nix. | |||
There was a problem hiding this comment.
Do we call them guides or how-to guides? This distinction feels pedantic to me but I cannot help raise it.
I'm generally in favor of guides as how-to seems implied by popular usage.
There was a problem hiding this comment.
Diataxis calls them how-to guides, which is probably a good-enough reason to do that as well.
My personal opinion is different: "how-to guide" is more characters and it's idiomatic - while "guide" has a real-world meaning that matches our purposes. But ease of recognition probably trumps my armchair linguistics.
|
I'm curious about the word choice of recipe and how-to guide. In my mind they seem synonymous. Do y'all have preferred word choice? |
Begin work of #910
|
Upon discussion at today's documentation meeting, I have decided to shelve the effort to write a how to for how to guides. |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2024-05-14-documentation-team-meeting-notes-126/45431/1 |
3 participants
Begin work of #910