Please do not make me click on "reference" to get to "API docs". I love diataxis, but dear lord, do not make me click an extra time to get to the thing I actually need 95% of the time.
Overall, the movement is good, except for how it tends to turn 1-click docs into 2-click docs (or more for folks who don't know that API docs probably live under reference.)
You are allowed to have a top level tab/link to API docs. Please do not hide those from me while you "improve" your docs.
I'm genuinely confused about what one would expect under "reference" that isn't effectively API-shaped (in the context of software). Like, I've never consciously thought of this before but I can't remember a time that they haven't effectively been synonyms in my mind when I'm navigatig documentation.
A lookup table of normative specifications for every API call is Reference material. But a tour of API concepts is not (that would be Explanation). Nor is a Tutorial that introduces the API.
A lookup table of normative specifications of CLI arguments would also be Reference.
So they are not synonymous.
To be clear, I'm not advocating for navigation that must always have this structure in cases where it's redundant. I think people should do what makes sense. But I think it is nevertheless useful to not mix the different categories.
That's part of the problem. Some projects, when they move to diataxis, will create a top level section called "reference" and have a single item under it called "API" (or similar.)
Depending on the docs theme, it can require clicking through to get to it.
It is a minor annoyance.
edit: Also gonna tack onto this that my original comment reads way more acerbic than I actually feel. I was sleepy and didn't proofread for tone like I normally do.
Oh like that. I was thinking of situations where "reference" just directly links to the API keyword index, e.g. the P5 docs[0], putting a redundant extra page between that would annoy me too.
They've always resonated with me, maybe because I often work on legacy code. All this ancient technology that no one understands. Crazy rituals/incantations to get things done. People being afraid to skip steps, even if it probably isn't needed. The aversion to unconsecrated (non IT-supported) technology.
The machine spirits were the only part that felt "too magical" to me, but now we're well on our way. The Omnissiah's blessings be upon us.
(Let's just skip servitors. Those give me the heebie-jeebies.)
Someone please explain the grapple leapfrog example and why that "exploit" is interesting. If my players tried that, I'd happily let them use their full turns to do some crazy trapeze act across the battlefield.
And then I'd remind them that they could have just dashed normally.
Moreover, how do the new rules close the "exploit"? You can still move 30ft while carrying someone. (60/2 - 30 vs 60 - 30*2) How is that difference meaningful in this case?
(Also, wouldn't you need something like rogue's dash-as-a-bonus
-action to grapple and dash on the same turn?)
The article is pretty interesting overall but this example mystifies me. Am I missing something obvious?
Yeah, both players were either rogues or tabaxi (although feline swiftness isn’t dashing)
This is also directly why I don’t like D&D. It is way too combat focused and video gamey. If your combat system is so complex that people find (or even feel that they need to find) “exploits” in it then your system probably sucks. So many class features are purely combat focused completely ignoring the actual roleplaying part of role playing games.
Also the “counter chaining” feels odd to me, is this something that actually happens? Like people waste spellslots counterspelling a counterspell?
From my limited experience, many players and DMs seem to get things backwards in exactly the way you're describing. They take the rulebook as the starting point or the "controls" for the game and since combat is the most detailed they tend to focus on that to the exclusion of other parts of the game. I've always viewed the rules as a way of settling disputes or uncertainty instead, so you start from the role playing and only resort to rules when you need fair adjudication or clarification on complicated situations. i.e. don't give me quotes from the rulebook, tell me what your character does and we'll work it out as part of the story.
When most of the games rules are about a thing that thing becomes the focal point. 5e also assumes pretty high amount of combat encounters per day to keep all classes in balance, if you are having less then it will make some classes just bad picks which can feel bad
Personally I don’t like it when people don’t play by the rules of the game we have decided to play together, so definitely things should work as the rules say and then ambiguous things are sorted with GMs world’s logic as “rulings”.
If you start by ignoring the rules and only consulting them when there is a dispute then I want to play another game with less rules to begin with
I guess it depends if you want the game to be a grind for the next level or if you want real interactive fiction. Different people like different things.
It really just depends on do you play D&D or something else. It is perfect fine if you don’t want to play by the rules, but then you aren’t playing the game and we might as well just stop pretending and pick a better system
> If your combat system is so complex that people find (or even feel that they need to find) “exploits” in it then your system probably sucks.
Couple of things.
1. People will try to find exploits in just about any system. That's kind of part of the fun.
2. If the difficulty curve sucks in a particular D&D campaign - that's the DM's fault, not the system's. Plenty of tools at DM's disposal to make campaigns less combat focused or being more lenient to players.
Eh, I don’t find it fun because if you can break the combat then you either decide not to play “optimally” or GM has to purposefully create situations to fuck with you specially which is just antagonistic
First one is pretty easy. The player is just trying to do RAW instead of intention. Intent obviously is that while dragging every feet of actual movement costs two of your characters movement allowance, so dropping the burden doesn’t give you more movement.
Countering a counterspell feels like a waste since for one you have to have another caster with counter spell and now they are wasting their reaction plus a slot instead of just going another round. I guess there are situations where that makes sense, but somehow feels bad
Odd, I don't see any mention of subprocess.run, the workhorse of python scripting.
Quick rundown for the unfamiliar:
Give it a command as a list of strings (e.g., subprocess.run(["echo", "foo"]).)
It takes a bunch of flags, but the most useful (but not immediately obvious) ones are:
check=True: Raise an error if the command fails
capture_output=True: Captures stdout/stderr on the CompletedProcess
text=True: Automatically convert the stdout/stderr bytes to strings
By default, subprocess.run will print the stdout/stderr to the script's output (like bash, basically), so I only bother with capture_output if I need information in the output for a later step.
Also `asyncio.subprocess`, which lets you manage multiple concurrently running commands. Very handy if you need to orchestrate several commands together.
By default (1) captures stdout and stderr of all processes and (2) create tty for processs stdout.
Those are really bad defaults. The tty on stdout means many programs run in "interactive" rather then "batch" mode: programs which use pager get output truncated, auto-colors may get enabled and emit ESC controls into output streams (or not, depending on user's distro... fun!). And captured stderr means warnings and progress messages just disappear.
For example, this hangs forever without any output, at least if executed from interactive terminal:
from sh import man
print(man("tty"))
Compare to "subprocess" which does the right thing and returns manpage as a string:
Can you fix "sh"? sure, you need to bake in option to disable tty. But you've got to do it in _every_ script, or you'll see failure sooner or later. So it's much easier, not to mention safer, to simply use "subprocess". And as a bonus, one less dependency!
(Fun fact: back when "sh" first appeared, everyone was using "git log" as an example of why tty was bad (it was silently truncating data). They fixed it.. by disabling tty only for "git" command. So my example uses "man" :) )
`sh` is nice but it requires a dependency. No dependencies is nicer IMHO. uv makes this way easier but for low dependency systems, or unknown environments stdlib is king.
I love how this import trick shows how hackable Python is - and it’s this very hackability that has led to so many of the advances we see in AI. Arguably without operator overloads we’d be 5 or more years behind.
I think the point is that for most things, you don't need to call any external tools. Python's standard library comes already with lots of features, and there are many packages you can install.
In JS, there are microtasks and macrotasks. setTimeout creates macrotasks. `.then` (and therefore `await`) creates microtasks.
Microtasks get executed BEFORE macrotasks, but they still get executed AFTER the current call stack is completed.
From OP (and better illustrated by GP's example) Python's surprise is that it's just putting the awaited coroutine into the current call stack. So `await` doesn't guarantee anything is going into a task queue (micro or macro) in python.
That doesn't make sense. That would mean the awaiting function doesn't have access to the result of the Promise (since it can proceed before the Promise is fulfilled), which would break the entire point of promises.
Oh yes! This works with other intensifiers as well. "Crazy good", "wicked bad", "mad smart", etc. To my ears, eliding the -ly changes the meaning from the literal reading, to specifically the intensifier reading.
Goodness, yes. The last time I put (genuinely constructive) criticism in a peer evaluation, it turned out to be the only non-positive thing that was said about that coworker. So it became a focus of his yearly review.
He later told me about how his review went (casually at a conference; he had no idea I was the source), and I fessed up and clarified what I actually meant. The HR process had twisted it to a much more extreme version of what I was getting at, completely undermining the utility of the feedback.
Nowadays, I'm just gonna give perfect scores and if I have feedback that needs to be given, I'll just tell the coworker directly. (And if I'm not comfortable doing that, then the feedback probably isn't important enough.)
I think a big factor of that is that usually most people just do the positive feedback and don't say anything negative or constructive. So when someone does do so, it's seen as "wow, this must be so bad that they just had to say something, no matter how delicately or toned-down it is being phrased as". These days I just mention the problems and concerns to the people making the decisions because yearly review time is the wrong time to do it. At best they've only been doing this "bad" thing for a month or so, and at worst almost a whole year and no one did anything.
Overall, the movement is good, except for how it tends to turn 1-click docs into 2-click docs (or more for folks who don't know that API docs probably live under reference.)
You are allowed to have a top level tab/link to API docs. Please do not hide those from me while you "improve" your docs.