Review Ticket: Running a Collaborative Research Website and Blog with Jekyll and GitHub

[JMParr]

The Programming Historian has received the following tutorial on 'Running a Collaborative Research Website and Blog with Jekyll and GitHub by @amandavisconti and @walshbr. This lesson is now under review and can be read at:

http://programminghistorian.github.io/ph-submissions/lessons/collaborative-blog-with-jekyll-github

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 François Dominic Laramée if you feel there's a need for an ombudsperson to step in.

Anti-Harassment Policy

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 Ombudsperson (@fdlaramee). He is serving as Ombudsperson in this instance, because @amandavisconti is the English Ombudsperson, and she is one of the authors of the lesson under review. Thank you for helping us to create a safe space.

[JMParr]

Edited to fix some formatting issues in the review ticket.

[jessesadler]

Thanks to @jmparr for the opportunity to review this lesson by @amandavisconti and @walshbr. I had been following along the year of blogging at Scholars' Lab, and so it was very interesting to go through this lesson and see the process. I think this lesson is very valuable and will help enable groups to build sustainable workflows for collaborative websites. I appreciate all of the screenshots and think that interested people will be able to be successful following the lesson. The lesson does a good job of discussing at the beginning that the difficulties associated with the lesson are not technical so much as social. As I note below, I think there are some more opportunities to make clear the division of labor and knowledge, in particular that setup is fiddly but not something most people working on the website will need to do or know about. In this way, the lesson is really divided into two: the setup and then the writing and reviewing workflow. This could probably be made more clear at the beginning of the lesson.

My comments are divided between general comments and specific comments that follow the hierarchy of sections set out in the lesson. I give some remarks on the sections and refer to the line numbers of the current version where possible. If you you have any questions, I am happy to respond.

General comments

• Clauses and explanatory notes in the lesson are a bit inconsistent. Sometimes they use em-dash and sometimes parentheses. I think that parenthetical statements are overused in the lesson. Many of them can just be sentences.
• The name of the repository is sometimes written with capitals (CollabDemo) and sometimes not (collabdemo). Would be better to just have one way of writing it.
• The hierarchy of headers is awkward from the "Moving an existing website to Jekyll" section on. That sections seems like it should be a second level header and the subheadings should be third level and not bolded. I think after this is when there should be a second level "Help" section referred to in p44 and the concluding headers could be level 3. In either, case, the hierarchy is unclear.
• After the Setup section, it might be useful to have a short introduction to the writing and posting process, which users will repeat much more often than anything done in the set up section. You could also note that this is the process that everyone needs to have some knowledge of, and that though the lesson has been made to minimize one's knowledge of how git works, some basic terminology is useful. There are four basic terms that are useful to know. As I note later, I do not think it is necessary to talk about versioning here. I think it could just be quickly mentioned as something people can look into.
  • Writing posts
    • Branches: Separate copies of the website repository. One branch will always be used to serve the content of the website. This is the "gh-pages" branch. Any changes to the website or new posts should be done in separate working branches.
    • Commits: The terminology used for saving your work.
  • Reviewing and publishing
    • Pull Request: Request to have the changes you have made on your working branch be brought into the branch used to serve the website. It is at this point that a review of the changes can occur.
    • Merge: The process of merging the changes made on the working branch with the branch used to serve the website. This is a commit on the primary branch.

Specific comments by section

Introduction

• Introduction
  • p32: The first sentence does not really describe what is in the actual lesson.
• How difficult is this lesson?
  • p44: There is no help section in the lesson. I think there just needs to be a second or third level header after the Drawbacks and limitations section.
  • Second paragraph seems a bit out of place. Could be reworked to more clearly demonstrate that it is talking about difficulty of lesson and that you will not be pushed to understand git or the command line.
• Scholarly case study: DH center research blog
  • p55: "website you'll actually work through over the course of this reading" – should be either through or over.
• Why might this setup fits your needs?
  • p62: Don't need "as well" at the end of the paragraph.

Setup: one time instructions for set up

• p62: One more sentence might be useful here to further introduce the process of setting up the blog.
• Import the demo repo
  • p72: Link to GitHub should be in angled brackets, not square brackets.
  • p76: Recommendation for the name does not need to be in parentheses.
  • p86: "We have one last thing to do - we need to" – should be made into two sentences or use a semi-colon.
  • p86: "we need to make a new branch (copy of our files) "gh-pages"" – add "called" before "gh-pages", since this is the name of the branch.
  • p94: Link to collabdemo repository should be in angled brackets, not square brackets.
• Set up Netlify
  • This section is clear.
• Set up your site for multiple authors
  • An overview of the steps at the beginning of this section would be useful. I also think that it would make it easier for people to understand why they are doing the steps. The actual steps are clear, but it would be nice to know what changes need to be made to make Jekyll recognize multiple authors.
  • p120: Sentence after footnote 6 is very long and is not clear.
  • p156: "In the top level of your repo folder" – should just be "In the top level of your repo"
  • p206: The last sentence does not need to be in parentheses.
• Reviewer permissions
  • Could emphasize that the steps to set this up may seem a bit fiddly, but they are not particularly difficult.
  • p260: This is a good overview of the process
  • p262: The second sentence is a bit difficult to follow.
  • p262: Could also emphasize more that this will help make the blog truly collaborative beyond just having multiple people post This could be done in a sentence at the end of the paragraph.
  • p264–267: These lines are broken up within sentences. The assumptions listed here would be more clear if they were individual sentences. If you do not want them to be sentences, there are commas missing.
  • p269: "Also, using branches lets you run checks such as Netlify" – should be "run checks on Netlify"
  • p296: Netlify is spelled incorrectly
  • p300: "upper- lefthand menu" – should be "upper-lefthand menu"
  • p322: Do not need parentheses with "(Even folks who always". There is also currently no closing parenthesis.
  • p324 and 325: Need a line space before image.

Authoring and Editing

• Introduction
  • p334 and 336: Not sure why bold is used here, especially in "two parts".
  • p336: There should not be a comma in the bolded sentence on creating a new branch.
  • p338: You may not need to explain merging here, as it is explained in the next section. Just state that it is a two step process and this is the first step.
  • p340: Should not be a comma after footnote 7 marker.
  • p340–344 Sentence describing how this lesson is different from the previous one is confusing. It may just eed some commas.
• Create a branch
  • This whole section is a bit confusing, and I think it can be simplified. The mentions of "repo" feel out of place and are confusing. Define branches as a copy of the website folder, or project, that you can make changes to without changing what is on the live website until you explicitly want to. Then give overview of creating a branch on GitHub.
  • p347: "before starting a new set of work, such as" – should be "before starting new work such as"
  • p351: I was very confused by this discussion of branches.
    • I do not think that repo needs to be defined here. I would also define it more simply as a folder or project.
    • The discussion of branches could also be trimmed down and made more clear.
  • p353: Link to repo should be in angled brackets, not square brackets.
  • p353: "default repo branch named" sounds odd. Either "default branch named" or "default branch of the repository named".
  • p367: These two sentences could be simplified to just say GitHub automatically moves you to the newly created branch. And move to next paragraph.
  • p369: It might be better to just note that the Branch dropdown menu will always indicate which branch you are on and that this is something you should always take care to note.
  • p375: I would say that you are now on a "new" branch, since you are always on a branch.
• Authoring and editing on GitHub.com
  • Intro
    • p378: "write a post or page's content" – should be "write a post or alter a page's content"
  • Create a new post
    • I would make clear that there are two ways to make a post: Make changes directly on GitHub or write in an external editor and then copy and paste. This second option is mentioned later, but I think it would be preferable and should be discussed immediately.
    • p399: Remove parentheses and make into two sentences.
    • p403: The markdown for the link to the section is reversed.
  • Committing, AKA saving your work
    • p406: I am not sure that the discussion of versioning is necessary here. It somewhat distracts from the main point, which is about making commits. I think versioning could be mentioned, but I am not sure it needs to be explained. In addition, this discussion could be above in the section on branching.
    • p408: Why the use of bold text.
    • p414: Remove "instead" in last sentence.
  • Adjustments to front matter
    • This section could come before the previous one on Committing.
    • p435: There are four changes listed, not three.
    • p454: This sentence is awkward: "This is just when the post will say it was published, in the URL and in the page metadata."
  • Checking how your post appears
    • p466–468: The formatting here is problematic. The reference to Netlify sounds as if this is a new thing, but we had to set up Netlify earlier in the lesson.

Reviewing and Publishing

• Create a pull request p476: I think that the terminology could go earlier as noted in the general comments. However, if you want it here, I think it would be better to be in the Intro subsection not in the pull request subsection. In addition, I think that the description of merging should come last.
  • p495: This sentence is awkward: "The page displays dropdown fields to indicate which branch you're comparing with (toward eventually merging into) which other branch."
  • p501: Take out "which" at the end of "(see the steps above on verifying which is your default branch if you're not sure which)"
  • p509: This refers to steps 1–2, but the steps are not numbered in the next section.
• Merging as an admin
  • This section is clear. It might be nice to say that the PR, review, and merge process may feel a bit odd at first, but once you have done it a couple of times it will get a lot easier.
  • p514: This paragraph could be shortened. This information has already been explained.
  • p516: This sentence is not necessary.

Drawbacks and limitations

• I appreciate this section and all of the wider writing on the need to be prepared for the difficulties that come with this workflow.
• p569: "onto a Jekyll" – should be "onto a Jekyll website"
• p573: Link to Scholars' Lab site should be in angled brackets, not square brackets.

Moving an existing website to Jekyll

• This section is clear and does a good job of laying out the pain points likely to occur during the process.
• This seems like it should be a second level header. The bolded subsections could then be third level headers.

Workflow recap

• The workflow recap and following sections seem like they should be under a "help" heading mentioned in p44.
• These points should be markdown list 1., 2., etc. not header list
• p597: Number 3 could be expanded: Create a pull request when you are ready to have your changes merged to the master branch
• p600: Number 6: Administrator merges accepted pull request
• p601: Number 7: Delete working branch used to make changes or create post

Footnotes

• Line spaces between the footnotes would help the formatting on GitHub.
• p651: Note 3: closing square bracket is missing in Debates in Digital Humanities.
• p652: Note 4: remove "over" in "updates the site over on our own servers"
• p652: Note 4: remove "other" in "site on other servers"
• p653: Note 5: remove "off" from "want to build off an existing"
• p655: Note 7: Make the parenthetical phrase a separate sentence. You do not need a comma in this sentence.

[JMParr]

Thank you very much for this very detailed review, @jessesadler ! We should be hearing from our second reviewer soon. After that 2nd review is in, I'll summarize the feedback, and make further comments.

[willismonroe]

Hi all, thanks for the opportunity to review the tutorial. I thought it offered a pretty clear way to get to a collaborative working environment based on Github/Netlify with a minimum of technical knowhow.

Overall it seems right on target, however I do think there is room for improvement. One issue I came across as you'll see in my review, was that the initial archive contained already modified files. That meant that steps of the tutorial were redundant. That's an easy fix though. Seems like @jessesadler has done the phenomenal work of going through the tutorial with a fine toothed comb so my review will offer some general comments after working through it myself.

Comments

The first paragraph throws a lot of links and jargon at the reader right away, I think these would be great in a follow-up paragraph make sure the reader is on the same page, sort of a pre-assessment, and a soft route for readers to quickly check up on the skills before diving in. In this scenario the first paragraph would server more as the hook, the general intro to what the reader hopes to get out of the tutorial.

I also think that the first sentence could be re-written to set a possible scenario for the reader: "This tutorial will show you how to create a blog with multiple authors representing the academic output of a collaborative research project or center" i.e. provide framing for the output. (Reading further now I see the case study example, this is great and exactly what I was thinking of, so maybe signposting this, and providing other short examples in the intro would help.)

I appreciate the recognition that the tutorial will not teach you how to customize the look of the site. However, I think for many readers this will be a turn off, they'll be expecting some rudimentary control over the look of the site (something that is so easy with Wordpress). Perhaps a short section on incorporating basic CSS or layout styles could be added as appendix. Otherwise you could also link to the huge number of tutorials on customizing Jekyll (I see you discussion of themes, and at least one link at the end).

At the end of the "Why might this..." section, you could perhaps speak to the idea of a Static-site generator and the performance and security benefits of this set up versus Wordpress. You discussed the comparative labor and time cost of the two in a previous paragraph.

In the initial upload of all the files, it would be good to get the reader in the habit of describing commits by having the title and describe the initial commit.

For the first edit of "_config.yml", the suggested changes were already present in my copy of the archive.

Likewise for adding _people, all of that content already existed in the archive I downloaded from the tutorial.

I'm confused about the creation of "author.md" with some content (including a "Biography" heading) and then the creation of a "writers.md" (which seems fine), and then going back and replacing "author.md" with new content (sans "Biography" heading). This feels like overwriting work I just did, and now I seem to have lost the option to have a "Biography" for each writer. I understand that the new "author.md" preserves the biographical content, but it's not initially clear. Maybe having the user test it out between overwriting the file would help them see the impact the changes make.

Minor point, my GitHub "Settings" page didn't have "Collaborators & teams" only "Collaborators"

The option "Restrict who can push to matching branches" I think only appears when there's more than one user on a repository (this might catch folks who are just forging ahead after sending of an initial e-mail invite to the repository, since the initial e-mail invite isn't enough to make the setting visible). So it turns out neither is having someone join your repository. Looks like the only way to make this setting appear is to be part of an "organization" (https://github.community/t5/How-to-use-Git-and-GitHub/Option-not-appearing-to-protect-who-can-push-to-a-branch/td-p/24479)

The link "review and publishing" points back to the entire tutorial.

The section "Don't forget to see" is repeats the material from two paragraphs earlier, there's probably a good way to combine those, or explain the changes in more detail.

At the end of the "Create a new post", there should be a short call to action to actually put some content into the new post so the reader can see the results of their efforts.

There should be guidance for creating and naming a new post. I was caught by the lack of a date in my filename, so I had to troubleshoot why the Netlify deployment wasn't showing my new content. Some stricter instructions here would probably save some headache later.

[JMParr]

Okay @amandavisconti & @walshbr - the reviews are in. Thank you for your patience. Here's my overview of the feedback:

To sum, it the reviewers would like to see some improvement to the introduction to make this tutorial more novice-friendly, as well as some improvements to the signposting. In particular, are there ways to reduce the jargon? Both recommended clarifying what readers can expect from the lesson. They’ve also flagged some proofreading issues, a paragraph that could perhaps be combined, and some areas where they would like to see you expand your explanations.

On the technical side of things, there were some additional recommendations:

• Give novice users a rudimentary background on the CSS and HTML, to offer some control over format. Perhaps there is an existing tutorial this one could link to?

• Review the creation of “author.md.”

• Address the problem with getting “the “Collaborators & teams” setting.

• Add some guidance for creating and naming a new post.

Is it possible to turn around revisions by 2020-March 4?

[amandavisconti]

Hi @JMParr @willismonroe @jessesadler! Thank you all so much for your thorough and helpful reviews, from both me and @walshbr. We believe we can provide revisions by March 4, 2020, as long as the following sounds okay to you:

We would be happy to recommend some links to tutorials about HTML and CSS, but would like to not provide a background on these in this lesson itself, for the reasons below. We actually had a section on advanced/further reading linking to such resources (based on the first Jekyll lesson's such section), but cut it to fit the word limit. Is it okay to add that back in, word-limit-wise?

In terms of covering introductory HTML/CSS: We think this topic is foundational and complex enough that it deserves its own lesson, in terms of author attention, walking readers through specific examples, and making sure ProgHist readers with other reasons for learning HTML/CSS would realize such a resource is available.

A group of Scholars' Lab staff have been discussing providing a sort of "Jekyll Lesson 3" that covers HTML/CSS issues specific to Jekyll/static site generators by walking folks through troubleshooting customizing themes, understanding files/plugins, command-line troubleshooting, etc. Discussing this generated some interest from potential readers on Twitter; we would be interested in pursuing this as a separate Programming Historian lesson in the future, should ProgHist be interested.

Thanks again for your generous and helpful work reviewing our lesson!

[JMParr]

Hi, @amandavisconti & @walshbr - March 4th sounds fine. Your suggestion of adding links to some tutorials about HTML and CSS also makes sense, particularly given the need to be mindful of length. There are plenty of good tutorials out there. I also like the idea of a separate Jekyll Lesson 3. I've seen plenty of discussions about Jekyll and queries about Jekyll-related skills on Twitter, so there's clearly an audience for it.

[quinnanya]

As a random and very interested lurker, just wanted to say that I'd be VERY ENTHUSIASTIC about a part 3. And if there were also a part 4 about ways of making a site multilingual, that would also be amazing. (I could help with part of that part 4 if you wanted a collaborator, but I don't have the Jekyll chops to do it myself.)

[mdlincoln]

And if there were also a part 4 about ways of making a site multilingual, that would also be amazing.

put a pin in this one for my hypothetically-due PH sabbatical, when I have time to write lessons again :)

[amandavisconti]

@mdlincoln Excellent! Quinn and I tweeted about this a bit, and she noted @JonathanReeve might be interested as well, re:his work on the Multilingual DH site.

[JonathanReeve]

Great article, @amandavisconti . I'm looking forward to seeing this published. And I'd be willing to help out with a tutorial in multilingual Jekyll, if someone else does most of the work. :smile:

One meta-comment I have about this tutorial, is that sometimes screenshots containing UI elements can be confusing. For instance, if you're on a webpage where you expect to see buttons, and then you see images of buttons, it can confuse you about what's real UI. Similarly, it can be tough to see the boundary between a page with a white background and an image with a white background. I recently tried to solve this problem here on open-editions.org by just adding a bit of shadow under the screenshots. So, this is not actually an issue with this article, but a suggestion for upstream, in the site CSS.

[amandavisconti]

@JonathanReeve Thank you!

[JMParr]

@JonathanReeve I would love to hear more about your multilingual Jekyll wrangling more generally.

[JonathanReeve]

@JMParr, It's nothing special, just the liquid expressions you see in this template. They read language codes from the YAML header data of the posts, and insert those where necessary. It's a bit of a hack, though. More modern static site generators have this functionality built-in. It's even nicer in a language like Elm, which has libraries like this one.

[amandavisconti]

Hi @JMParr! @walshbr and I have completed revisions based on your and the reviewers' kind advice.

(In case it's useful for future reviewing, I'll note that some of the reviews discussed formatting issues that only appear when you read the GitHub file interface version of the lesson, i.e. this, but do not appear when reading the actual rendered lesson webpage, i.e. this. It might be useful to explicitly link reviewers to the latter?)

[JMParr]

Thank you, @amandavisconti & @walshbr for getting this finished so quickly. I'll review it this weekend and follow up.

[acrymble]

Just a note that related to COVID-19, @JMParr will be unavailable until 15 April 2020 (she isn't ill thankfully). @svmelton as Managing Editor can respond to any questions from the authors or reviewers (though keep in mind that she too may be facing new pressures related to the virus, so responses may be delayed).

Thanks for your understanding everyone.

[svmelton]

Hi @JMParr! Now that you're back from sabbatical, are you ready to revisit this? Let me know if it would be helpful for someone else to take this on or if we're ready to move to copyediting.

[JMParr]

Hi, @svmelton This is ready to move to copyediting.

On Tue, May 5, 2020 at 11:37 AM Sarah Melton notifications@github.com wrote:

Hi @JMParr https://github.com/JMParr! Now that you're back from sabbatical, are you ready to revisit this? Let me know if it would be helpful for someone else to take this on or if we're ready to move to copyediting.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/278#issuecomment-624129739, or unsubscribe https://github.com/notifications/unsubscribe-auth/AFNO4WYZDRDJ45XUCTJQ32LRQAXDXANCNFSM4KBQ6VHQ .

[svmelton]

Thanks @JMParr! @amandavisconti and @walshbr, I'm going to begin soliciting copyeditors and will be back in touch once they've completed their edits.

[walshbr]

Sounds good! Thanks.

[amandavisconti]

@svmelton Thank you!

[svmelton]

Hi @amandavisconti and @walshbr—the copyedits have been completed and can be found here. Please let @JMParr know when you've completed the edits and she can begin the publishing process!

[walshbr]

Thanks! We'll be in touch if we have questions.

[walshbr]

@svmelton - we're working through our copyedits over here. We're aiming to get this in by the end of August - hope that's alright. That will allow us to account for time out of the office, other short-term work that needs addressing, and the unfortunate fact that github updated their UI in the last couple weeks. Want to make sure that the screenshots and instructions still work as expected - I don't expect we'll need to recapture things just because the aesthetics have changed, but I want to make sure that nothing has moved around.

[JMParr]

This is fine on my end! I have a manuscript deadline, and we're also being paid to develop our courses for online delivery in the fall. I'll be less swamped in August.

On Wed, Jul 1, 2020 at 4:13 PM Brandon Walsh notifications@github.com wrote:

@svmelton https://github.com/svmelton - we're working through our copyedits over here. We're aiming to get this in by the end of August - hope that's alright. That will allow us to account for time out of the office, other short-term work that needs addressing, and the unfortunate fact that github updated their UI in the last couple weeks. Want to make sure that the screenshots and instructions still work as expected - I don't expect we'll need to recapture things just because the aesthetics have changed, but I want to make sure that nothing has moved around.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/278#issuecomment-652623677, or unsubscribe https://github.com/notifications/unsubscribe-auth/AFNO4W7PNYJJZERTNEJFSMLRZOKGRANCNFSM4KBQ6VHQ .

[walshbr]

Done @svmelton and @JMParr!

[svmelton]

Hi @JMParr! Checking in on this—when do you think you'll have this ready for me to do the final publication steps?

[JMParr]

Hi, Sarah- I will try to take care of it by the end of the week.

On Sun, Sep 27, 2020 at 12:02 PM Sarah Melton notifications@github.com wrote:

Hi @JMParr https://github.com/JMParr! Checking in on this—when do you think you'll have this ready for me to do the final publication steps?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/278#issuecomment-699653625, or unsubscribe https://github.com/notifications/unsubscribe-auth/AFNO4W4HP2DXQJMATQT7EU3SH5O2VANCNFSM4KBQ6VHQ .

[svmelton]

Hi @walshbr and @amandavisconti! Just a note that I've finished the editorial check and will be beginning the publication process.

[svmelton]

And we're live! Thanks to @walshbr and @amandavisconti for all your work, @JMParr for serving as the editor, and @willismonroe and @jessesadler for your reviews!

You can see the piece here.

[walshbr]

Yay! Thanks, all!

[amandavisconti]

Thanks everyone!