3 ms·

I thought the hand drawn windows were well done for what they were, but for a beginner audience I wonder if real screenshots do more or less to help with the "a

I thought the hand drawn windows were well done for what they were, but for a beginner audience I wonder if real screenshots do more or less to help with the "aha" moments of connecting the tutorial instructions with output the user anticipates. At the same time, the hand drawn windows probably make the tutorial less intimidating to the target audience-of which I'm not a member. But got me pondering how I can improve my own documentation in a few areas. Curious what others might think.

seabird 8y ago
This is a situation where I would argue that giving "exact" images of the output is not helpful, and I'm somebody who normally hates fruity presentations of info. Having the reader make their own associations allows it to be applicable across environments and develops what I'll go ahead and call "Rambo problem-solving", where you must get from point A to point B, even if that means you have to improvise or roll in the mud a little. You can't go off the beaten path with most GUIs, so being able to with a CLI is one of its most compelling uses. The reader needs to associate the command with the info, and not the presentation of it.
- schoen 8y ago
  I never thought of that, but on reflection I think you're exactly right that hand-drawing is a good way to focus the reader's attention on the content of the text and not on the surrounding visual context. With a screenshot, the user might be consciously or unconsciously wondering why the terminal window looks different if it's a different OS/terminal emulator/font.
  - iamdave 8y ago
    Agreed. I hadn't really thought of that either and consider me convinced of the point made.
  - Retra 8y ago
    That issue would be better solved by just typing the text in a code block, no?
    - jolmg 8y ago
      I feel that goes too far in the other extreme. They might not be able associate the examples with their own environment if the prompt is different (besides username and host; a different $PS1). Having the window representation makes for having more to associate, like "yes! I too have a window with a bit of text at the top and empty space below and to the right!" Having drawings also allowed for those arrows and text to explain the content, so that's great.
- AnIdiotOnTheNet 8y ago
  This is one of the reasons I'm a fan of Powershell, it's incredibly discoverable. Tab completed (with cycling) parameter names, names like Get-X/Set-X with consistent name mappings between them, pipelining with objects so there's no string parsing footguns, and Get-Member.
shazow 8y ago
Having shared these zines with beginners IRL (hi, I did the cover!), I can say that the abstract nature of the terminal makes it less intimidating but does not remove from the content. I imagine for an intermediate/expert audience who has established an intimate relationship with the intricacies of the actual UI, screenshots could work fine. For people who barely have an idea of what this thing is, cutting the cruft in a friendly way is good. Print one out and give it to a friend, see what they think. :)
- pvg 8y ago
  One thing that can be made obvious in a drawing is the distinction between what the user is expected to type, what's already on the screen when they start typing and what the output after they've finished typing (and hit enter) is. For some reason, the drawings in this intro don't do that. I also probably wouldn't give a friend unfamiliar with the command line a tutorial that teaches 'rm' and 'sudo' this early on.
  - shazow 8y ago
    One of the goals of the zine is to get people up to speed with what they need to know to learn programming--good to have a goal while you're learning, right? When setting up Python (and really most languages), you end up needing things like sudo. Really it was one of the missing pieces of content that beginners needed to get into Tracy's other books like https://hellowebbooks.com/learn-django/ https://hellowebbooks.com/learn-django/.
    - pvg 8y ago
      You don't need sudo to set up Python (and probably most commonly used languages). But beside that, I don't think rm and sudo are the third and fourth thing you should be typing into a terminal, whatever your end-goal. If you haven't seen it before, an ancient but worth-thieving-from example of a beginner programming manual is 'The Applesoft Tutorial'.

seabird 8y ago

This is a situation where I would argue that giving "exact" images of the output is not helpful, and I'm somebody who normally hates fruity presentations of info. Having the reader make their own associations allows it to be applicable across environments and develops what I'll go ahead and call "Rambo problem-solving", where you must get from point A to point B, even if that means you have to improvise or roll in the mud a little. You can't go off the beaten path with most GUIs, so being able to with a CLI is one of its most compelling uses. The reader needs to associate the command with the info, and not the presentation of it.

schoen 8y ago
I never thought of that, but on reflection I think you're exactly right that hand-drawing is a good way to focus the reader's attention on the content of the text and not on the surrounding visual context. With a screenshot, the user might be consciously or unconsciously wondering why the terminal window looks different if it's a different OS/terminal emulator/font.
- iamdave 8y ago
  Agreed. I hadn't really thought of that either and consider me convinced of the point made.
- Retra 8y ago
  That issue would be better solved by just typing the text in a code block, no?
  - jolmg 8y ago
    I feel that goes too far in the other extreme. They might not be able associate the examples with their own environment if the prompt is different (besides username and host; a different $PS1). Having the window representation makes for having more to associate, like "yes! I too have a window with a bit of text at the top and empty space below and to the right!" Having drawings also allowed for those arrows and text to explain the content, so that's great.
AnIdiotOnTheNet 8y ago
This is one of the reasons I'm a fan of Powershell, it's incredibly discoverable. Tab completed (with cycling) parameter names, names like Get-X/Set-X with consistent name mappings between them, pipelining with objects so there's no string parsing footguns, and Get-Member.

shazow 8y ago

Having shared these zines with beginners IRL (hi, I did the cover!), I can say that the abstract nature of the terminal makes it less intimidating but does not remove from the content. I imagine for an intermediate/expert audience who has established an intimate relationship with the intricacies of the actual UI, screenshots could work fine. For people who barely have an idea of what this thing is, cutting the cruft in a friendly way is good. Print one out and give it to a friend, see what they think. :)

pvg 8y ago
One thing that can be made obvious in a drawing is the distinction between what the user is expected to type, what's already on the screen when they start typing and what the output after they've finished typing (and hit enter) is. For some reason, the drawings in this intro don't do that. I also probably wouldn't give a friend unfamiliar with the command line a tutorial that teaches 'rm' and 'sudo' this early on.
- shazow 8y ago
  One of the goals of the zine is to get people up to speed with what they need to know to learn programming--good to have a goal while you're learning, right? When setting up Python (and really most languages), you end up needing things like sudo. Really it was one of the missing pieces of content that beginners needed to get into Tracy's other books like https://hellowebbooks.com/learn-django/ https://hellowebbooks.com/learn-django/.
  - pvg 8y ago
    You don't need sudo to set up Python (and probably most commonly used languages). But beside that, I don't think rm and sudo are the third and fourth thing you should be typing into a terminal, whatever your end-goal. If you haven't seen it before, an ancient but worth-thieving-from example of a beginner programming manual is 'The Applesoft Tutorial'.