This semester we will be engaged in a class-wide project to create a repository of information about software engineering concepts, techniques, frameworks, and people.
Overview
Starting in week 3, each week you will be asked to draft an essay on a topic of your choice that is related to software engineering. These essays are due by 11:59 PM on the Wednesday of each individual week. Then, over the remainder of the week, you must pick three essays and review them. Your reviews should be short and to the point, offering constructive criticism for the original author. These reviews are due by 11:59 PM on the Sunday of each individual week. If you look at an essay and it already has three reviews, then find another essay to review.
Note: The information for this assignment is also available on the wiki of our GitHub repo.
This assignment will last for 10 weeks, ending with the essay written in week 13 (plus the reviews).
Instructions for Essay Creation
To submit an essay, create a page in the wiki and name it after the topic you are writing about. Then, use Markdown to provide information about the topic. Each essay should be only two to four paragraphs that describe the topic at a high level and offer pointers for interested readers to learn more. Be sure to include a section at the end of the essay to indicate who wrote the essay. See the example essay for details.
It is important that each essay properly cite any text not written by the author of the essay. You can cite text using a block quote. Here's an example that cites text from Wikipedia about software frameworks:
In computer programming, a software framework is an abstraction in which software providing generic functionality can be selectively changed by additional user-written code, thus providing application-specific software.
Frameworks are really useful and it would be cool if a student decided to write more about them!
Essays can contain links, images, text, code… anything you want to use to provide information about the topic that you are writing about. If you would like to include an image in your essay that does not live on the web, then contact Prof. Anderson to learn what you need to do to add the image to our repository such that you can then link to it. (Hint: Prof. Anderson already did this when he created the markdown-version of No Silver Bullet.)
Once you have submitted an essay, be sure to:
- Edit the sidebar to contain a link to point to the new essay.
- Add an entry to the author index that points to your new essay.
When updating the sidebar, feel free to update its hierarchical structure to best classify your essay. If you feel uncertain about where to put your essay, go ahead and put it somewhere and someone else may come along and move it to a different place. I suspect that eventually, we'll settle on a classification scheme that works for the vast majority of essays.
The author index will make it easy for me to find all of the essays that you eventually create.
Instructions for Essay Review
To review an essay, you will go to its page and click on the edit icon. You will then add a section at the bottom of the article that looks like this:
---
<Your Name>:
<Insert Review here>
---
When reviewing the essay, you should indicate what you liked about it and then offer constructive criticism. The latter can include recommendations for additional points that could be made, links to other references that might be relevant, and pointers to related topics within our wiki. If the essay contains typos, feel free to fix them when performing your review, as long as you do not change the intent of the author with your updates.
Here's an example review:
Ken Anderson:
I liked your essay because it discussed a type of software framework that was new to me. I will have to learn more about NoSQL databases, especially the ones that can process large graphs. I think you can improve this essay by showing an example query for the database you discussed in detail. You showed me code that inserted information into the database—and that was cool—but now how do I get the data back out? Overall, good work.
When you read the reviews of your essays, it is perfectly fine to update your original essay in response. If you do update the article, then make a note in the review to indicate how you responded to the reviewer's comments. To do that, you can add a paragraph to the review and prefix it with a checkmark emoji. Here's an example:
Ken Anderson:
I liked your essay because it discussed a type of software framework that was new to me. I will have to learn more about NoSQL databases, especially the ones that can process large graphs. I think you can improve this essay by showing an example query for the database you discussed in detail. You showed me code that inserted information into the database—and that was cool—but now how do I get the data back out? Overall, good work.
✅ Thanks for your comments, Ken. I have added code to the essay that shows how to submit a query to Cassandra and then how to process the results.
To have your response stand out from the original review, enclose it in asterisks to make it bold.
Once you have finished your review, save the page, and then edit the reviewer index to point at the essay that you reviewed. This will make it easy for me to see all of the reviews that you generate over the semester.
Comments on Peer Review
I am adding a peer review component to this assignment since this is a skill you need to develop as a software engineer. You will be frequently reviewing the artifacts that are created by your team members: code, design documents, technical papers, etc. You need to learn how to generate criticism that leads to increases in the quality of those artifacts. Please strive to keep your comments constructive and, on the flip side, be open to the comments that you receive from others. Taking criticism and responding to it in a positive way is also a skill you need to develop. 😀
Wiki Documentation
If you have never used GitHub's wiki feature before, be sure to review the documentation.