78 Matching Annotations
  1. Feb 2018
    1. suport


    2. The method to connect to the database is explained above.

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

    3. a gsub function

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

    4. ‘’

      code format?

    5. and we have to handle that case if we have data with apostrophes

      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" ?

    6. these functions are here for an example only.

      Nice explanation!

    7. Run this program

      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

    8. ```

      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.

    9. Update the R program above


    10. o


    11. Success! you have connected to the database.

      (and disconnected after that, right?)

    12. “SomethingDifficult”

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

    13. Add

      "And save the file"?

    14. Add this statement to the newspaper_search.R program library(RMySQL)

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

    15. In RStudio create a program named newspaper_search.R by making a new R script and saving it.

      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.

    16. If you don’t have the library RMySQL installed

      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)..." ?

    17. Run this instruction per below:

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

    18. Documentation is here: https://cran.r-project.org/web/packages/RMySQL/RMySQL.pdf

      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.)

    19. this

      "our existing"?

    20. All of this can be done with a command if you prefer:

      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...)

    21. done with a command

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

    22. Tip: Take your time to think about table design and naming since a well designed database will be easier to work with and understand.

      Yes! I like this.

    23. A table is the structure that holds the data we want to store. Tables hold many rows of records. An example record of basic contact information would contain fields for name, phone number and e-mail address for data Pat Abraham, 613-555-1212, pat@zmail.ca. In a table, fields are organized into columns.

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

    24. type:

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

    25. In the Query window type:

      Should users delete the previous CREATE DATABASE command?

    26. if necessary

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

    27. Beside SCHEMAS

      Lower left of screen

    28. Run the CREATE DATABASE command. Click

      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.

    29. Run

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

    30. Local Instance MySQL57

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

    31. Here we will create a database which serves as a container for the tables we will store our information into.

      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".

    32. mysql>

      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.

    33. Reboot

      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?)

    34. Start a MySQL session: mysql --user=root --password=[the_root_password_you_wrote_down_above] Set the root password to a new password. Write this down carefully. mysql> SET PASSWORD=PASSWORD('[your_new_password_you_just_wrote_down]'); Reboot

      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.
    35. [

      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?:





    36. Add /usr/local/mysql/bin to the PATH per the command below

      Brief explanation what PATH is here?

    37. You can download R from the Comprehensive R Archive Network. Click on the link that matches your computer’s operating system. Select base to install R for the first time. Once downloaded, click on the file to run the installer.

      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?

    38. Your root password will be different.

      "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)

    39. ![Setup Type: Developer Default](http://jeffblackadar.ca/getting-started-with-mysql/getting-started-with-mysql-6.png “”)

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

    40. To do this lesson you will need a computer with R and RStudio installed on it and where you have permission to install more software.

      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?

    41. However, there are times when databases are very useful including: Placing the results of an R program on a web site where the data can be interacted with. Handling large amounts of data. Storing the results of long running programs so that a program can continue from where it left off in case it was interrupted.


    42. R language

      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?

    43. Using a database also offered the ability to recover from errors when my R program stopped during processing. Since the database stores the most recently processed work, the R program was able to begin from where it left off before it ran into an error. This was very important because I did not want to waste days of processing by starting over from the beginning.

      Excellent explanation!

    44. relational database

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

    45. I wanted to make further improvements to the finding aid by using natural language processing

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

    46. Introduction

      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)
  2. Jan 2018
    1. Installation tips for a PC:

      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?

    2. Run the CREATE DATABASE command. Click on the lightning bolt or using the menu, click Query Execute Current Statement.

      Layout got a bit messed up here?

    3. Using MySQL Workbench

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


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

    4. MySQL Installation instructions: https://dev.mysql.com/doc/workbench/en/wb-installing.html MySQL Workbench downloads: http://dev.mysql.com/downloads/workbench/

      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."

    5. ;

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

    6. Create a database

      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?)

    7. finding aid

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

    8. first finding aid

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

  3. Nov 2017
    1. Graphs Are Everywhere

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


  4. Jun 2016
    1. keep the following in mind:

      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.

    1. Download the Java Development Kit.

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

  5. Mar 2016
    1. NodeJS

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

    2. You’ll need to be a Mac user

      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

    3. Xcode

      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.

    4. why might I care?

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

  6. Jan 2016
    1. slack-invite-script

      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.

    2. in getMyHost() fill in your slack domain

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

    3. fill in your slack api token

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

    4. fill in the channel you want to send updates to

      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?

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

  7. Dec 2015
    1. using the magic of Hypothesis

      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!

  8. Mar 2015
    1. reading might be described as the continual redisposition of levels of address in this manner

      Another useful (and cool) definition

    2. Physical texts were already massively addressable before they were ever digitized, and this variation in address was and is registered at the level of the page, chapter, the binding of quires, and the like.

      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.

    3. massive flexibility in levels of address

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

    4. The book or physical instance, then, is one of many levels of address.

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

    5. Now, we are discussing ideal objects here: addressability implies different levels of abstraction (character, word, phrase, line, etc) which are stipulative or nominal: such levels are not material properties of texts or Pythagorean ideals; they are, rather, conventions.

      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?

    6. Because a text can be queried at the level of single words and then related to other texts at the same level of abstraction: the table of all possible words could be defined as the aggregate of points of address at a given level of abstraction (the word, as in Google’s new n-gram corpus).

      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?).

    7. a text is a text because it is massively addressable at different levels of scale

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

    8. What does it mean to be an “item” or “computational object” within this collection? What is such a collection?

      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.

    9. New experiments provide opportunities for thought that precede the results.

      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.