search

programminghistorian / ph-submissions

The repository and website hosting the peer review process for new Programming Historian lessons
http://programminghistorian.github.io/ph-submissions
138 stars 113 forks source link

Review Ticket for Intro to Twitter Bots With Tracery #75

Closed JMParr closed 7 years ago

JMParr commented 7 years ago

The Programming Historian has received the following tutorial on 'Introduction to Twitter Bots With Tracery' by shawngraham. This lesson is now under review and can be read at:

http://programminghistorian.github.io/ph-submissions/lessons/intro-to-twitterbots

Please feel free to use the line numbers provided on the preview if that helps with anchoring your comments, although you can structure your review as you see fit.

I will act as editor for the review process. My role is to solicit two reviews from the community and to manage the discussions, which should be held here on this forum. I have already read through the lesson and provided feedback, to which the author has responded.

Members of the wider community are also invited to offer constructive feedback which should post to this message thread, but they are asked to first read our Reviewer Guidelines (http://programminghistorian.org/reviewer-guidelines) and to adhere to our anti-harassment policy (below). We ask that all reviews stop after the second formal review has been submitted so that the author can focus on any revisions. I will make an announcement on this thread when that has occurred.

I will endeavor to keep the conversation open here on Github. If anyone feels the need to discuss anything privately, you are welcome to email me. You can always turn to @ianmilligan1 or @amandavisconti if you feel there's a need for an ombudsperson to step in.

Anti-Harassment Policy

This is a statement of the Programming Historian's principles and sets expectations for the tone and style of all correspondence between reviewers, authors, editors, and contributors to our public forums.

The Programming Historian is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutinize ideas, to ask questions, make suggestions, or to requests for clarification, but also provides a harassment-free space for all contributors to the project, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion, or technical experience. We do not tolerate harassment or ad hominem attacks of community participants in any form. Participants violating these rules may be expelled from the community at the discretion of the editorial board. If anyone witnesses or feels they have been the victim of the above described activity, please contact our ombudspeople (Ian Milligan and Amanda Visconti - http://programminghistorian.org/project-team). Thank you for helping us to create a safe space.

shawngraham commented 7 years ago

Just a note, comment left by hypothesis user https://hyp.is/DqxqgDsEEeeY9edgKGCQ5w/programminghistorian.github.io/ph-submissions/lessons/intro-to-twitterbots so I need to change the language appropriately at that point.

shawngraham commented 7 years ago

just wondering where we are in the process

JMParr commented 7 years ago

Hi, Shawn- The tutorial went out for peer review a few weeks ago. I'll send a follow up to the reviewers to see where things stand.

On Tuesday, June 6, 2017, Shawn Graham notifications@github.com wrote:

just wondering where we are in the process

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/75#issuecomment-306578628, or mute the thread https://github.com/notifications/unsubscribe-auth/AVruWzn9gJJ7Ae-G2spsqobf36y-KDMWks5sBZycgaJpZM4NUMfA .

acrymble commented 7 years ago

In the interests of internationalisation and political neutrality, I would like the 'Russian hacker' reference to be changed.

JMParr commented 7 years ago

Fair point.

On Mon, Jun 12, 2017 at 12:41 PM, Adam Crymble notifications@github.com wrote:

In the interests of internationalisation and political neutrality, I would like the 'Russian hacker' reference to be changed.

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/75#issuecomment-307846128, or mute the thread https://github.com/notifications/unsubscribe-auth/AVruW292oHSGkXNjZsLYQV1KnpRgh1K2ks5sDWosgaJpZM4NUMfA .

shawngraham commented 7 years ago

@acrymble yes, a user via Hypothes.is made the same point. Fair enough.

Readywriting commented 7 years ago

Hey everyone! Sorry for the delay on this feedback!

My biggest piece of feedback is that I would personally love to see an "intermediate" bot broken down. You refer to them, and say, well, you can see it and figure it out. But, maybe going through and actually breaking down that process would be helpful for a beginner (like me), where I have long struggled with making that next-step bot. Conversely, you could break down how you did one of yours.

I also have to say, in section 28 where you point out it's missing the word "I" and you say to add it, you don't say how. And I don't see it in the JSON that is created. Did you not add it or did I miss it?

Let me know if you have any questions about this feedback. I'll admit to needing more hand-holding than many, but I think moving the person beyond the rudimentary syntax would be really helpful.

JMParr commented 7 years ago

Thank you, Lee. Could you elaborate just a bit more specifically on what sorts of addenda would be helpful. Since we have readers of very diverse technical skill, I think this would be helpful as far as helping Shawn figure out just how much elucidation you're looking for, and where you're getting lost.

On Mon, Jul 10, 2017 at 12:57 PM, Readywriting notifications@github.com wrote:

Hey everyone! Sorry for the delay on this feedback!

My biggest piece of feedback is that I would personally love to see an "intermediate" bot broken down. You refer to them, and say, well, you can see it and figure it out. But, maybe going through and actually breaking down that process would be helpful for a beginner (like me), where I have long struggled with making that next-step bot. Conversely, you could break down how you did one of yours.

I also have to say, in section 28 where you point out it's missing the word "I" and you say to add it, you don't say how. And I don't see it in the JSON that is created. Did you not add it or did I miss it?

Let me know if you have any questions about this feedback. I'll admit to needing more hand-holding than many, but I think moving the person beyond the rudimentary syntax would be really helpful.

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/75#issuecomment-314168317, or mute the thread https://github.com/notifications/unsubscribe-auth/AVruWwS9h9NRz-iK0gR4Ytk69W44pCnlks5sMlflgaJpZM4NUMfA .

Readywriting commented 7 years ago

So, nesting and making a more complex bot. I get the initial syntax, but then, if I look at one of the other tracery examples I get completely lost. So, is there a way we can have the idea of "nesting" explained to make more complicated tweets. Breaking down, not just sentences, but paragraphs (understanding they will only be 140 characters).

shawngraham commented 7 years ago

Ah, cool, right. Thanks Lee! I sometimes suffer forest-for-the-trees, so I appreciate this. Lemme see what I can do...

shawngraham commented 7 years ago

I've included more information on the way symbols can be nested to create more complex bots or text, including how to save variables for reuse and so on. Trust this makes the lesson clearer. Also switched to 'black hat hackers' in the intro

BTW, the new ProgHist layout is very cool on the live site - kudos!- but I find it makes reading this lesson in progress kinda hard. Paragraphs used to be numbered, didn't they, when the lesson was in review? Anyway, doesn't really matter. Just an observation. You could use Hypothesis groups, have a unique group for editor, reviewers and authors to annotate things up. Thanks.

acrymble commented 7 years ago

Hi @shawngraham, thanks for this tutorial and sorry you've had to wait so long for a second review. It's an interesting public history/public humanities approach that I'm sure a number of people will find useful. I've read through this and I have a number of comments, mostly to do with the language. I've used paragraph numbers (thanks for pointing out the problem with the new design).

Minor point:

p2 - 'Twitter bots' not 'twitter bots'. p8 - write out 'API' for first use, and link to Twitter API page. p8 - why would I need Python for a bot? (assumed understanding) p8 - link generative grammar to wikipedia (more links to Wikipedia generally would be good) p8 - link Cheap Bots Done Quick p15 - "We can begin to think of an ‘being’ symbol:" is the 'an' correct here? p31, 32, 34, 54 - what is 'JSON'? What are keys and values? p32, 33 code should be in a code block. See https://programminghistorian.org/author-guidelines p42-46 - this hard to read. can you format as a list or table? p55 - will the +tag trick mean you're unable to ever reset the password of the account?

Broader points:

What is a bot? After reading paragraphs 1-3, I wasn't actually clear what a 'bot' was. I think you also have to be careful to distinguish between a 'Twitter bot' and a 'bot', which are two different things. While your examples in paragraph 3 are fun, I actually assumed there was one out there finding new planets, but instead when I clicked on it (which I presume most readers won't do), found it was just stringing together words that could sound like planet descriptions. On a related note, the Congress-spying bot is actually doing two things: 1 it's scanning Wikipedia for edits of a certain kind. 2 it's using a Twitter bot to post the results of that scan. You can't learn to do that by doing this lesson. This is all to say that I think you need to make the opening much clearer: 'A Twitter bot is...it is made by..."

Why do historians/humanists care?

The 'every 3 minutes' example is really strong, but it could be much more explicit exactly what it does and how a 'bot' helps achieve it. Framing this as an outreach project that engages audiences in real time without requiring active maintenance will help people understand how this fits with the outreach work they might want to do.

You put forth a case in p40, but if that's important to your case, it has to be earlier.

If this was up to me, I'd make this a clearer case for a public history project that could semi-automate some of a project/institutions' duties, rather than purely rely on its 'fun' appeal.

Your examples are rarely historical

One of the key advantages of the Programming Historian is the historian-first approach to examples. The Rangers vs Habs example is effective because it demonstrates a point, but why have you chosen to make a bot about a flower pot? Can it at least be an ancient piece of pottery or something with a historical bent? And can you come up with a realistic (rather than 'fun') reason why this ancient pot will help you in your role as a public humanities scholar? For example, we use it to Tweet about published lessons at regular intervals. Though ours doesn't randomly string things together, which could be difficult to put this to more serious use.

The language & tone is very colloquial

You've adopted a real persona to the writing, which fits with your emphasis that this is meant to be fun. I can read this fine because we're both culturally North American. But I don't think this would be very easy for an English-second-language, or even a British person in some cases. For example you refer to a 'botstorm', talk about 'bricoleur', and adopt a number of rather abstract phrases 'art and whimsy' that could be challenging for some readers.

Related to that, some of your examples assume cultural understanding. Bob Ross was a brilliant artist who touched the lives of millions of people with some time to kill after school in the 1980s and 90s, but no one outside of North America will know him. Your hockey example might need a note in the figure caption that this is a tweet about a hockey game. Otherwise it is just a string of meaningless words. And I don't remember 'mad libs', so I felt a bit alienated from your example. Can you simplify/un-funnyify the language as a means of making the lesson more culturally relevant and easier to translate into Spanish? About four steps towards formal would be helpful all around, I think.

Sustainability This lesson seems heavily reliant upon two free services, and I'm worried it won't last more than a few years.

Is there any way to future-proof the lesson by telling users what they'd be looking for in the future if these services disappeared? You need a X, rather than 'use this website'?

--

I hope that's helpful feedback. It's an interesting idea for a lesson, and something that I think could fit well with the public history offerings. Let me know if you need any clarifications.

shawngraham commented 7 years ago

Thanks @acrymble . some really good points. I'll see how I can roll these things into my text, thanks!

shawngraham commented 7 years ago

Regarding sustainability, it is possible to make a twitter bot powered by tracery, python, tweety, and so on: but that's a whole other lesson. Would it be fine to just point towards something like this https://botwiki.org/tutorials/twitterbots/ ?

shawngraham commented 7 years ago

I do want to make the point that I think programming for historians can and should involve whimsy and creativity, to push what digital history could be, and not necessarily be about outreach when it's not about analysis. I mean, I had no idea what somebody might do with sonification, but then Jim's student blew us all away with where he ran with it.

ruebot commented 7 years ago

Sorry it too me a while on my review :disappointed:

Paragraph 22:

Paragraph 25:

Paragraph 31:

Paragraph 32:

Paragraph 74:

Paragraph 79:

Nice work @shawngraham!

JMParr commented 7 years ago

@shawngraham I am satisfied with pointing to another tutorial, although you're certainly welcome to propose additional lessons if you're inclined.

And thank you to both @acrymble and @ruebot for their reviews.

shawngraham commented 7 years ago

Thank you @ruebot! Also, @JMParr I'll point out to other resources; with my crafting digital history course on right now, I'm all tutorial'd-out

shawngraham commented 7 years ago
elikaortega commented 7 years ago

Hi Shawn and Jessica, and others. As usual, apologies for the delay! I thoroughly enjoyed your tutorial! You really do a great job outlining the process of building a bot and especially, how to come up with ideas. I look forward to seeing this tutorial out. Below are some minor recommendations and punctual comments: