| title | author | date | reviewers | layout |
|---|---|---|---|---|
Get Involved |
default |
Whether you have found a mistake in a lesson, have new ideas for lessons we should add, want to contribute lessons of your own, or have constructive criticisms on how to improve the site, we want to hear from you!
From our own experiences as well as from our authors, we know that the difficult job of writing technically challenging but accessible tutorials is one of the best ways to teach yourself particular skills and actively engage in the community by passing on some of the tacit knowledge gained along the way.
Submitting a lesson also brings distinct professionalization benefits. We prominently feature the names of authors and reviewers on all of our lesson pages, as well as the contributors page, and new lessons tend to be frequently tweeted and retweeted. Because we average more than 100,000 unique visitors per year, The Programming Historian remains a vibrant and visible site for community collaboration and education.
We don't simply accept or reject articles like traditional journals. Our editors collaborate with you to help craft and hone your topic and approach, as well as to make your tutorial as clear and as useful as possible.
There is no single kind or standard lesson at The Programming Historian. We do insist that all lessons have a clearly defined goal and are written with a particular audience in mind. Ideally, readers must understand at the outset exactly what skills or results they will achieve by working on a lesson, and the lesson will conclude only after it has provided a tangible skill to the reader. We aim for lesson that take between 30 minutes and 1 hour to complete. More expansive lessons can be divided into smaller sub-lessons that can be worked through in sequence.
The Programming Historian is committed to open source and open access principles. All contributed lessons must make use of open source programming languages and open source software whenever possible. This policy is meant to minimize costs for all parties, and to allow the greatest possible level of participation. We believe everyone should be able to benefit from these tutorials, not just those with large research budgets for expensive proprietary software.
The Programming Historian also emphasizes sharing credit where it is due. Upon acceptance, authors agree to release their lesson under a Creative Commons Attribution 3.0 Unported license, also known as a "CC-BY" license. This means that you have the right to post your lesson to your blog, to your local newspaper, or to anywhere else you see fit without asking anyone's permission. However, you grant PH and anyone else interested in your work the right to do the same as long as they list you as the author. This allows the lessons to have the greatest possible diffusion and impact.
Rather than offering lessons in a set order, we present more of a smorgasbord, enabling readers to pick and choose whatever particular lessons seem most relevant for their task at hand. We aim for our lessons build and draw upon each other. As a author, this means that you don't need to explain in detail smaller tasks, technologies, or techniques that have been explained in their own tutorials, but can focus on the problem you're most interested in. This allows authors to write tutorials more directly aligned with their interests, and for us to minimize our repetition across lessons.
Lessons must make every effort to use stable, non-deprecated (or soon to be deprecated) techniques, languages and software. Alpha versions of software should be avoided; Beta versions only used if they are extremely stable. We discourage operating-system specific tutorials, but we are happy to work with you to get your tutorial tested on other platforms so that everyone can learn from them.
Lessons should be written in Markdown, a lightweight syntax that helps us to generate our site using GitHub Pages. For more information about how lessons should be formatted, see our Markdown Style Guide. New authors should also consult our editorial workflow for new lessons.
Please feel free to contact us with questions or suggestions. We'd love to hear from you.
Reviewing for the Programming Historian is a great way to learn new technical skills (at any level) and engage with the digital humanities community at the same time. We go out of our way to make sure our reviewers get ample credit and recognition for their work. Because reviewers directly contribute to significantly improving lessons, you can take pride in how your work helps our many thousands of users.
Our peer review process is a bit different from what might be considered the "traditional" peer review process. We do not solicit reviews to judge whether a tutorial is "good enough" to be published. Rather, we consider the review process an integral component of a collaborative, productive, and sustainable effort for scholars to create useful technical resources for each other. Once a tutorial slips into our editorial workflow, our goal is to do everything we can to make sure the tutorial becomes as useful as possible and published in a reasonable amount of time.
To review a tutorial is not simply to assess its merits and flaws (though it is important to do these as well), or judge whether it's appropriate for Programming Historian, but to help improve the tutorial as an outside reader. We ask that reviewers comment on tutorials as they would on a paper or similar for a colleague--to provide fair and constructive criticism (and of course praise) that will improve the tutorial for a wide range of readers. We don't send anything out for review that isn't within a reasonable distance of publishable quality. A few extra perspectives and suggestions (beyond those of the editor) greatly improve lessons and make them of great (and unique) value to the community.
We highly value transparency in our lesson production and review process. Our review process happens at Github, where our lessons are hosted. Namely, we use Github's commenting and issue tracking capabilities to keep track of suggestions and how they are handled and discussed by the authors and reviewers. This helps avoid important conversations becoming lost in archived email threads. Future tutorial users can easily rekindle a old conversation that has become newly relevant.
Therefore, your work as a reviewer--and your identity--will be fully visible to the author. Comments should engage with the author and lesson directly, rather than the review editor. If you as a reviewer would like to share some comments privately with the reviewing editor, you are welcome to email those separately, but we aim for as much transparency as possible.
Unless you instruct us otherwise, your name will be indicated as a reviewer on the lesson's page at Programming Historian when it is officially published; you'll also be listed on our contributors page. These are, of course, insufficient tokens of appreciation, but we want to emphasize that Programming Historian is the work of volunteers and give credit where credit is due.
The informal style of Programming Historian lessons can make the lessons appear deceptively simple to write. In fact, writing a good tutorial is every bit as demanding, if not more so, than any other kind of scholarly writing. Below are a few common questions to keep in mind as you review a lesson. Some will be more relevant than others, depending on the topic, intended audience, and the difficulty of the tutorial. Needless to say, this is neither a restrictive or comprehensive list; we do not ask that reviewers respond to each and every question, but hopefully they can provide some general guidance.
If you haven't dabbled much at the Programming Historian already, you'll see that there is no standard audience across all the lessons. Some are for complete beginners, others are for those considerably more comfortable with technical concepts and methods, and yet others are directed toward experienced digital historians looking to solve difficult technical challenges. We welcome such variety!
While we like each of our lessons to take the unique voice of its author, we also want each individual lesson to remain clear and consistent in its tone. More specifically, we want the technical explanations (and difficulty) to remain as constant as possible throughout the lesson. As a reviewer, it is quite useful to note any sections of a tutorial directed at more technically advanced users that seem to over-explain relatively simple concepts; the converse is true, too: we want to avoid sections of tutorials aimed at beginners that don't adequately explain fundamental concepts central to the tutorial. Some questions to keep in mind:
- Does the author address a consistent model reader throughout the lesson?
- Are some concepts or steps over-explained while other are under-explained?
- Does the audience seem to match at least vaguely with other Programming Historian lessons? How is it new?
- What software / programming languages are required?
- What prerequisite skills are needed?
- What familiarity or experience is needed?
- What data is needed? Is it readily available?
- Are there clearly defined learning objectives or set of skills near the top of the lesson?
- Are there useful secondary skills to be gained / practiced from the lesson?
- Do screenshots and other diagrams illustrate crucial steps / points of the lesson?
- Do sections and section headings provide clear signage to the reader?
- Does the tutorial suggest why the explained tools or techniques are useful in a general way?
- Does the tutorial suggest how a reader could apply the concepts (if not concrete steps) of the lesson to their own work?
- Should a long lesson be divided into smaller lessons?
- Are there logical stopping points throughout the lesson?
- If data is required, it is available to download at various points throughout the lesson (or different versions of it as the tutorial may require)?
- Does the lesson build upon an existing lesson and explain how?
- Does the lesson tie into existing lessons and have appropriate links?
We manage all our peer review comments through the issue tracker on Github--that is, your reviewer feedback will take the form of a Github "issue." In order to create these, you should follow the directions on our Github Wiki. You can create multiple issues, of course, if you're commenting on different sections of the lessons. However you decide to partition your review is entirely up to you and how you want to conduct your review.
You can report a problem or make suggestions by following our instructions on how to create an issue in our GitHub repository.
Or you can email Fred Gibbs with any comments, questions, complaints, or suggestions. We endeavor to respond to all emails within three working days.
If writing a lesson isn't for you, perhaps you are ...
-
Interested in teaching humanists about technology?
-
Wanting to learn new digital humanities tools and techniques, and help teach others about them?
-
Hankering for editorial experience you can get credit for?
-
Teaching a digital humanities course where students might produce lessons that could be published here?
As a way of editing lessons as fast as our contributors can generate them, soliciting new lessons that would best serve our readers, and most quickly responding to our readers' needs, we'd love your help. We're particularly interested to engage with new editors who can help recognize potential new lessons that would serve a particular community need, and work with lesson authors to guide new lessons through the revision process with an exacting eye for clarity and style.
Have you ever wanted some editorial experience? Want to help shape the kinds of lessons that appear at Programming Historian? Whatever your interest and availability, we're happy to have your help whenever you can make time for us. There is no minimum amount you have to do, and we won't randomly demand that you do something without asking.
We're not asking for a long-term or an intensive commitment. The workload can be however little or much as you'd like. Our hope to is to establish a pool of editors so that all new lessons can be edited, revised, and published as fast as possible without any bottlenecks, calling on whomever is available at that time.
-
Learn: Editing tutorials is a great way to learn about new tools and techniques.
-
Visibility: Your work as a editor/reviewer will be well publicized at Programming Historian, so everyone will know how awesome you are.
-
Network: Get to know people working on really cool stuff and wanting to share it.
-
Karma: Contribute to a good cause.
If you'd like to be involved as an editor or reviewer, please email Fred Gibbs with a bit of information about yourself, namely the specific skills, tools, topics, and technologies that you'd like to be involved with so that we can send you the most appropriate lessons to review.
Thanks for making Programming Historian such a great resource!