Review for Extracting Keywords

[fredgibbs]

Reviewers: Please add your reviews as comments to this issue. Thanks!

[guymcclellan]

[guymcclellan]

[acrymble]

Thanks. @fredgibbs am I waiting for another review before I address this?

[fredgibbs]

Yes, there is one more overdue review that I expect literally any day now.

On Wed, Oct 21, 2015 at 7:05 AM, Adam Crymble notifications@github.com wrote:

Thanks. @fredgibbs https://github.com/fredgibbs am I waiting for another review before I address this?

— Reply to this email directly or view it on GitHub https://github.com/programminghistorian/jekyll/issues/116#issuecomment-149888066 .

frederick w gibbs | assistant professor of history | univ. of new mexico fredgibbs.net | @fredgibbs http://www.twitter.com/fredgibbs

[asmorton]

This lesson very clearly explains its objectives at the outset, and consistently provides section outlines and summaries that make it easy for the user to follow its progress from beginning to end. The required dataset is easily accessible and particularly suited to the lesson goals, and the author provides useful links to those of us unfamiliar with its contents. I would suggest, however, that this introductory section include either a more detailed explanation or a link to a tutorial on processing data to make it more accessible to those of us dealing with problematic sources.

The meat of the lesson is divided into logical sections that help to break up what would be fairly long sequences of code, and there is a clear break between the introductory-level sections and the more advanced option at the end. I particularly appreciated the construction of the individual sections. It is quite easy to get lost in the middle of longer Programming Historian lessons, but the individual sections within this lesson give the user markers for specific steps accompanied by expected outcomes and a clear outline.

Code snippets and screenshots are liberally used to illustrate the progress of the extraction, and as the previous reviewer mentioned, links to Wikipedia and to previous lessons make it easy for users to follow along as the language and code progresses. The author also provides helpful hints on how to use additional recommended software, which keeps the lesson at an introductory level and does not assume that users automatically understand how to clean up and manage datasets or use text editors.

I also appreciated the author’s foresight in including the troubleshooting note near the bottom—understanding common errors and helping users avoid the frustration of stopping mid-tutorial to find them is something I would like to see more in coding tutorials. In fact, the author consistently took care to guide the user through the more challenging parts of the lesson and to point out common problems they might encounter with Python and the recommended software tools.

While I did appreciate the inclusion of links to previous Programming Historian lessons within the later sections of the lesson, having a section near the beginning that provides links to these at the start might allow the user to have some of these lessons open and gain some familiarity with where this tutorial fits in the larger sequence of lessons.

[acrymble]

Thanks to you both for these comments. Just so I don't jump in and do this wrong, @fredgibbs do you want me to proceed with revisions, or do you want to take a different approach for the next step?

Thanks again.

[fredgibbs]

@acrymble, yes, I think you should proceed with revisions, especially since the reviews are quite positive and the suggestions relatively easy to implement if you agree with them. But I think the tutorial is in excellent shape and will only improve with whatever additional work you'd like to put into it.

[acrymble]

Ok just to summarise what I see in terms of change suggestions:

1) Suggestion to link to Geocoding tutorial by Fred Gibbs as an example of why you might like to do this type of task [done] 2) Increasing emphasis on hypothetical research question possible through this approach with this dataset [done] 3) Look for additional places to add troubleshooting bars. 4) Beef up intro's discussion of data management or link to another tutorial and consider the challenge of difficult sources [done] 5) A discussion near the beginning of which other PH tutorials are relevant would be helpful for the reader. [done]

I will work on those and report back. Let me know if I have missed anything.

[acrymble]

Ok I've gone through and made the above changes. This primarily involved adding to the 'For Whom is this Useful?' section, and adding a new 'Further Reading' section at the end.

I didn't see any obvious places to add troubleshooting bars.

Please let me know what you think.

[fredgibbs]

i think this is great! i think all we need to do now is add it to the lessons page, no?

[ianmilligan1]

Looks good to me! I just merged #61 so I think we could kill two birds with one stone perhaps?

[acrymble]

Thanks. We need to update the YAML block, but otherwise ya, just a matter of finding a pretty picture from @ahegel 's collection.

On Tue, Nov 24, 2015 at 10:00 PM, Ian Milligan notifications@github.com wrote:

Looks good to me! I just merged #61 https://github.com/programminghistorian/jekyll/pull/61 so I think we could kill two birds with one stone perhaps?

— Reply to this email directly or view it on GitHub https://github.com/programminghistorian/jekyll/issues/116#issuecomment-159417961 .

[acrymble]

I found a picture for this, but the instructions on the wiki don't explain how I upload the picture to github:

https://github.com/programminghistorian/jekyll/wiki/Lesson-Images

Do I actually have to do the 8-step proceedure listed here just to add an image for a lesson?: http://programminghistorian.org/new-lesson-workflow

[ahegel]

If you link me the original image source I'm happy to upload it for you using the usual procedure! For the other lessons we've uploaded both the cropped and the original image as per https://github.com/programminghistorian/jekyll/wiki/Lesson-Images. @acrymble

[ianmilligan1]

:+1: I uploaded them for Adam when I was putting the markdown image up, so we're good on that front.

[acrymble]

Thanks. I've posted this under Data Manipulation. Thanks to our reviewers.