spelling

Hyperlink to section so folks can easily look back at this?

define? (I'm not sure if that's needed, since the definition should immediately become apparent...)

code format?

Wasn't sure if there's a useful way to expand what this means for novices: "i.e. use of apostrophes means something specific in SQL, just like the INSERT command, and so we need to treat apostrophes appearing in our content specially" ?

Nice explanation!

For readers who might not be sure if they're entering this in the program or console): Add the following to your newspaper_search.R file, save, and press... (the "run" button seems to only run the line of the program your cursor is on? what should readers do here to run the whole program? I selected the whole text of the program and then clicking "run" seemed to run the whole thing, but that seems inelegant?) Edit: looks like that is just how RStudio is? https://stackoverflow.com/questions/12766276/running-entire-r-code

Tried to fix code formatting here–I edited spacing and it seemed to fix it in the lesson display here, but hasn't shown up on this page—possibly because the GH Pages site takes a bit to rebuild.

(newspaper_search.R)

in?

(and disconnected after that, right?)

Replace smart quotes with straight quotes, so copying/pasting into console doesn't produce error

"And save the file"?

I can't figure out where/how to do this.

Maybe some extra steps: Open RStudio, which you installed earlier in this lesson (link to where). We'll now use RStudio to make a new R script, save the script, and use it to create a program named newspaper_search.R. Go to File > New FIle > R Script, then save that new file as newspaper_search.R.

For folks new to this—"If you don't already have the library RMySQL installed (which is likely, if this is the first time you're using RStudio)..." ?

"After opening RStudio, copy and paste the following into the left window at the > prompt, then press enter." ?

Hyperlink; maybe also tweak this to make clear you can ignore this link if you don't have questions? E.g. (If you're curious, documentation for the RMySQL package is here.)

"our existing"?

I like that you offer both options. Since most readers will have already created the table as you describe in the previous step, I wonder if either a comment here (or editing the command) showing how to add these columns when you've already created the table, could be useful? (I realized that entering the command as-is even though I already created the table worked fine, but I wasn't sure what would happen...)

Where would the user go to enter this command—back to the query tab?

Yes! I like this.

Good explanation—I know I mentioned above maybe defining what a table is—could move this text up there, or leave as is.

Should users click the lightning bolt after typing this (and all future commands typed into the query window)?

Should users delete the previous CREATE DATABASE command?

"if you don't already see an item called 'newspaper_search_results..."; "click the refresh icon (see screenshot below)"

Lower left of screen

I got briefly stuck on the first sentence before noticing the second sentence says how. Maybe "Run the CREATE DATABASE command by either clicking on the lightning bolt icon in the upper left, or choosing Query > Execute Current Statement in the menu." Actually, I'm still stuck—the lightning bolt is grayed out/unclickable, as is the menu option. I tried both while the command was highlighted, and while the command was not highlighted. I also saved the file and then tried.

For clarity, maybe "To run the CREATE DATABASE command, click..."

On a Mac, I only see "Local instance 3306"

Apologies if I missed this (and maybe it makes since farther above)—could be useful to have a basic description of database terms before this, e.g. so users understand "database", "table", "query".

I copied and pasted this in and was confused at first—might be good to set mysql> prompt outside of code or otherwise visually differentiate, so folks know to not paste that part in.

How? (E.g. reader might not know to type exit to get out of mysql prompt—do they just need to exit and log back in?)

Step 3 was giving me an error:

mysql: [Warning] Using a password on the command line interface can be insecure. ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2) Steps that solved this for me:

1. Going to System Preferences > MySQL icon at bottom > clicking "Start MySQL server"
2. Remove brackets from Step 3 text and replace with single quotes around 'password' (brackets instead of single quotes did not work) That got me into MySQL.

Wasn't sure if these brackets are part of the command or not—I'm guessing not given the username isn't in brackets, so might be good to add a note so readers don't leave the brackets in when pasting their actual root password in?:

--password=mypassword

vs

--password=[mypassword]

?

Brief explanation what PATH is here?

I missed this step initially because it came after some separate reading recommendations. I really like the links you give in the two previous paragraphs, though—wonder if there is some way to visually ID actions lesson readers need to take?

"temporary root password" = the password the prompt gives you; "root password" = your normal computer password? (some readers may not think of this as a "root password"/themselves as "root user" on their machines)

A number of these image links are broken throughout—possibly the empty "" at the end of each?

Does the reader need to already have these things installed, or just have a computer with permission to install these and the lesson will walk them through that?

Nice

I know there's a good way to google questions about R that gets search results actually about the R language... but can't remember what it is. Might be nice to mention that someone in the less, maybe in a tips section?

Excellent explanation!

Brief definition of relational database for folks who don't know exactly what a database is (beyond e.g. "stores stuff")

Could you provide a brief definition of NLP here, so that novices understand why you wanted to use it?

I really like how you situate this lesson as a response to a real scholarly problem you ran into! You might consider preceding this with a few skimmable points so that visitors can tell whether the lesson fits their needs or not. E.g. with my lesson, I started with:

1. a single-sentence summary of why you might want to read the lesson (novice-friendly language)
2. what you'll be able to do by the end of the lesson
3. any software/hardware requirements
4. difficulty level of the lesson (do you need any previous knowledge? e.g. knowing what a "finding aid" is or how to make an HTML file like your first index example)

I don't have easy access to a PC but can test these steps on a Mac—let's see if we can have one of the lesson reviewers use a PC?

Layout got a bit messed up here?

I was not sure how to get to the window you screenshot—opening MySQL Workbench on a Mac produces this:

https://imgur.com/a/YGHvL

I found I needed to go to File > New Query Tab. Could be nice to add that as a parenthetical direction for Mac users?

These sites can be kind of intimidating for novices. What about instead linking to just this page and telling readers to scroll down, choose their operating system from the drop-down, and click the blue "download" button to the right. Maybe with "Ignore the text on that page and just scroll down to click the "No thanks, just start my download.' link at the bottom of the page. Once the file has downloaded, open it and follow the instructions to finish installation."

(It looks like this semi-colon is either missing from the screenshot, or hidden under the green line?)

Consider starting each section with a sentence on why you're doing that step, e.g. "Next, we'll create the database we'll use to store our data". (I know these feel kind of self-evident, but also kind of welcoming to novices?)

Possibly also include a screenshot here? (That way the lesson breaks less if your personal site changes)

Possibly include a screenshot of top of this file (showing just the first couple items) here?

Don't look now, I'm just a friendly reminder

Permissions (what user accounts on your computer are allowed to access, edit, etc. various files) differ from person to person, but if you ever enter a command and get a message that you're not allowed or don't have permission to run that command, try entering the same command except prefaced with the word sudo plus a space. If the command xcode-select -install returned a message that you don't have permission to execute that command, for example, you would instead try entering sudo xcode-select -install. Type your computer's password and press enter when prompted to do so. (This lets your computer know you have permission to execute this code.) In general, permission defaults are around for a purpose, and a lot of permissions are tied to the root/admin user to make them hard for anyone not sure what they do to accidentally open their computer to risks, but it should be safe to use sudo for any command in this lesson.

On Wikipedia

An early chatbot: On Wikipedia

I searched the linked page for this phrase and couldn't find it... took me a minute to realize JDK = Java Development Kit.

Wait, is NodeJS still a requirement for Jekyll 3.0 on Mac? Doesn't seem to be needed on Windows...

Note: this annotation is orphaned because I've changed the lesson text to support Windows. Keeping it here for posterity (and until I figure out if there's a way for Hypothesis users to edit what's highlighted).

Jekyll isn't officially supported for Windows, which means none of the official Jekyll documentation (the pages that walk you through setting up Jekyll and what its different pieces do) addresses Windows use. But! There are two Jekyll+Windows resources that Jekyll "unofficially" links to: http://jekyll-windows.juthilo.com/ and https://davidburela.wordpress.com/2015/11/28/easily-install-jekyll-on-windows-with-3-command-prompt-entries-and-chocolatey/

I'm a Mac user generally, but I tested setting up Jekyll on Windows and I believe that the things you'd want to do differently in this lesson if using Windows are:

1) Skip everything in the "Installing Dependencies" section: you won't need Xcode or Homebrew (which are Mac things) or NodeJS (not sure why, but the 2nd of the 2 links above suggest this is true?), and the instructions for Ruby/Ruby Gems and Jekyll rely on those and are thus incorrect for Windows user.

2) We need a command line tool that recognizes the same commands Macs and Linux computers (i.e. Unix operating systems) do [need to change this in the lesson, which erroneously just says to use the "Command Prompt" tool and doesn't have a Windows-only install step].

Visit https://git-scm.com/downloads and click on the "Windows" link under 'Downloads". Once the download has finished, double-click on the downloaded file and follow the steps to install Git Bash (leave all options the way they already are).

3) At the "Installing Dependencies" point in the lesson, instead enter at a command prompt the steps David Burela suggests, which are as follows...

Open "Command Prompt" (open your Start Menu and search for "Command Prompt" and an app you can open should come up).

Install Chocolately (a package manager, like Homebrew is for Mac)

@powershell -NoProfile -ExecutionPolicy unrestricted -Command "(iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))) >$null 2>&1" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin

4) Close the "Command Prompt" app and open "Git Bash" (which you recently installed) instead. You'll now use Git Bash any time the command line is called for (note that the Mac command line app is called "Terminal"—I'll try to make sure the lesson uses an operating-system-agnostic term).

5) Install Ruby (this will take a few minutes; don't forget to wait and not enter anything into the command line until the prompt appears again)

choco install ruby -y

6) Close the command line program and restart (Ruby won't work until you've done this once)

7) Install Jekyll (if Windows Security gives you a warning popup, ignore it)

gem install jekyll

I've just tested these steps on a PC, but I might have missed other Windows-specific things throughout the lesson. If you use Windows and run into issues, please let me know! I

If you haven't already installed Xcode (you'd probably remember if you did), the installation process can take 2-5 hours. Wondering if I should include a warning about this at the beginning of the lesson, so you know you'll want 10-20 minutes (?) to read the start of the lesson and begin installing Xcode, and then a separate amount of concentrated time (1-2 hours??) to complete the rest of the lesson.

I'd appreciate thoughts on whether this section's background info is too much (or not enough).

Much thanks to @dherbst for creating this—a very useful tool for Slack, which doesn't currently let users sign themselves up for your teams. I used this for the Digital Humanities Slack (tinyurl.com/dhslack) invite form.

Unfortunately, I neglected to note how I did the one fiddly part when following these instructions—finding your Slack channel code—and some colleagues are now stuck on getting that part to work. I've tried to annotate these docs with more info and questions to help others use them, too.

Replace the URL in line 3 of code.js. Should take the form: yourslackteamname.slack.com

Replace the fill_in_your_api_token in Line 8 with your token (should look like a longish number/letters)

I remember this part took me a bit to figure out, and now I can't remember what I did to see my Slack team's channel codes. Anyone have more specific instructions for finding your channel codes?

Wrote this with one ear listening to digital book project hacking at the CODEX Hackathon, so I'm blaming any infelicities on that!

I'm not sure manually embedding a link with the Via prefix is the way for me to go in the long run, but I bet some sort of use of Hypothesis is!

Another useful (and cool) definition

Always like seeing acknowledgement that scholarly primitives haven't changed, just our means for doing them. Stephen Ramsay's Reading Machines is a good, quick read about this in terms of digital humanities algorithmic criticism.

The ability to fluently read/react with a text at a given level of address be treated as a literacy.

Definition for manifestations of the text. Maybe useful in discussing interface as the encountered work?

Might be useful in thinking about what an “edition” is—must it include all items most editions currently include, or are those conventions or manifestations of values, and not necessary values themselves?

I like this idea of defining a level of text and than comparing across texts—would like to see more of this at the level of code and interface design and tool design decisions (e.g. how do different digital archives deal with making sure visitors see more than the alphabetically or chronologically first few items in the collection? how do different DH sites allow people to comment? what is the difference among moderation or voting systems?).

I think this is my favorite definition of “text” (as humanities scholars use the term) that I’ve encountered.

This is a great example of the type of critical thinking involved in scholarly digital building—often such projects include hard thinking about the exact nature of scholarly objects. Patrick Murray-John has a fantastic article that further discusses “where the theory is” when scholars design and build (Theory, Digital Humanities, and Noticing). The penultimate paragraph in particular lists some of the critical questions that arise out of designing for an “item” in a digital archives platform.

And even if we don’t yet have a way to run and experiment and/or gather results, we can use “speculative experiments” to learn about digital objects (such as a digital edition) by imagining and designing for a hypothetical and/or future circumstance.