Fall 2024
Allegheny College
Department of Computer and Information Science
| Class Time | Lab Time | Classroom |
|---|---|---|
| M/W/F 01:30pm-02:20pm | W 02:30pm-04:20pm | Alden Hall 109 |
- Hang Zhao
- Email: hzhao@allegheny.edu
- Office Hours:
- M/F 11:00am-12:00pm, 2:25pm-3:25pm (Alden Hall 105)
- W 11:00am-12:00pm (Alden Hall 105)
- Tue 12:00pm-1:00pm (Google Meet)
- By appointment:
- Schedule here for in-person meeting
- Schedule here for virtual meeting
An introduction to the creation of effective documents and documentation using industry-standard approaches to creating and treating "documentation as code". Through project-based and hands-on activities, students create purpose-driven digital writing, emphasizing the forms, formats, and conventions expected in contemporary technical communication. Students also gain experience in creating collaborative and ethically-consistent content within a team-based setting. During a weekly laboratory session, students employ contemporary software tools to complete technical documentation projects, reporting their results through written reflections and oral presentations.
The study of Human Experience explores human physical, mental, emotional, and/or spiritual experiences as conveyed in texts broadly defined. Through engagement with such texts, students develop an appreciation for human experiences and their representations.
Learning Outcome: Students who successfully complete this requirement will demonstrate an understanding of how to interpret human experiences as conveyed in texts (including works of visual and performance art, rituals, cultural artifacts and traditions, and/or the written and spoken word).
Courses involving Scientific Process and Knowledge aim to convey an understanding of what is known or can be known about the natural world; apply scientific reasoning towards the analysis and synthesis of scientific information; and create scientifically literate citizens who can engage productively in problem solving.
Learning Outcome: Students who successfully complete this requirement will demonstrate an understanding of the nature, approaches, and domain of scientific inquiry.
For more information, refer to Distribution Requirements: Learning Outcomes.
- Objective 1: Describe and explain processes such as software installation or design for a variety of technical and non-technical audiences ranging from inexperienced to expert.
- Objective 2: Use professional-grade integrated development environments (IDEs), command-line tools, and version control systems to compose, edit, and deploy well-structured, web-ready documents and industry-standard documentation tools.
- Objective 3: Build automated publishing pipelines to format, check, and ensure both the uniformity and quality of digital documents.
- Objective 4: Identify and apply appropriate conventions of a variety of technical communities, tools, and computer languages to produce industry-consistent diagrams, summaries, and descriptions of technical topics or processes.
A WIFI-ready device is necessary to follow along with course material. You will be instructed on which software to install on your device during the semester.
| Component | Percentage |
|---|---|
| Class Participation | 10% |
| Exam | 15% |
| Ten Lab Assignments | 5% each |
| Final Project | 25% |
| Grade | Percentage Range |
|---|---|
| A | 96% and above |
| A- | 90% - 95% |
| B+ | 87% - 89% |
| B | 83% - 86% |
| B- | 80% - 82% |
| C+ | 77% - 79% |
| C | 73% - 76% |
| C- | 70% - 72% |
| D+ | 67% - 69% |
| D | 63% - 66% |
| F | 60% and below |
- Class Participation: Regular participation in class activities is essential for your success in this course. Class participation will be based on your active participation in every class through in-class discussion and exercises.
- Exams: One mid-term exam administered in person. All work submitted for exam must be yours alone. Discussing exam questions with anyone during the exam period violates academic integrity expectations for this course. Note that no make-up exam will be given and absence from the exam will be recorded as a zero, unless the absence is excused by a documented emergency or religious observance.
- Laboratory Assignments: There will be a total of 10 Lab assignments, due via Github Classroom by 11:59 PM on the given due date. For late assignments, please refer to the tokens policy. Feel free to collaborate in discussing approaches and answers to the problems in small groups. However, each student should turn in a separate, individually prepared set of answers.
- Final Project: The final project requires you to apply the cumulative knowledge and skills from the course to produce a comprehensive set of documentation for a software project. This project will involve creating user manuals, technical architecture documents, and deploying these documents via a JAMstack-powered website. Additionally, you will set up a system that automatically updates and redeploys the documentation whenever changes are made. The project will be assessed on completeness, accuracy, adherence to industry standards, clarity, and the effectiveness of the automated update process. Students must submit individual work along with personal reflections on the process.
| Topic | Weeks | Due Dates |
|---|---|---|
| Git and GitHub | Weeks 1-3 | Assignment #1 due 9/6, Assignment #2 due 9/13 |
| Vscode | Week 4 | Assignment #3 due 9/20 |
| Technical Writing | Week 5 | Assignment #4 due 9/27 |
| Markdown | Weeks 6-7 | Assignment #5 due 10/13 |
| Wiki | Week 8 | Assignment #6 due 10/18, Midterm Exam during class period |
| RST | Week 9 | Assignment #7 due 10/25 |
| JAMstack | Weeks 10-11 | Assignment #8 due 11/8 |
| HTML | Weeks 12-13 | Assignment #9 due 11/22 |
| Metadata | Week 14 | Assignment #10 due 12/6, Final Project due TBD |
| Final Project | TBD | TBD |
Please feel free to visit and discuss course concepts with the instructor or Technical Leaders (TLs) whenever you need assistance.
Technical Leaders' office hours
To participate in lab assignments and access course materials, you will need a GitHub account. Please follow these steps:
-
Sign Up for GitHub
- Go to GitHub and sign up for an account if you do not already have one.
- Make sure to use your Allegheny College email address (
@allegheny.edu) when signing up, as this will be required to link your account to the course. - Be sure to add a current photo of yourself when completing your profile. Adding this photo will help your instructor to get to know you and your work, and to attribute the correct grades for your submitted work to you.
-
Link Your GitHub Account to the Course
- Once you have created your GitHub account, you will receive an invitation link when the first lab assignment is ready.
- Click on the invitation link and follow the instructions to link your GitHub account to the course.
- After accepting this initial invitation, you will automatically have access to all future lab assignments.
-
Accessing Lab Assignments
- After linking your GitHub account, you will be able to access all lab assignments through GitHub Classroom.
- Each lab will be distributed as a separate GitHub repository, where you will complete and submit your work.
If you encounter any issues while creating your GitHub account or linking it to the course, please reach out to the instructor or TLs for assistance.
When you are assigned a lab or project, you will be given your own repository containing the necessary materials. This repository is where you will complete your work. You will save your files locally on your computer and then push them to GitHub, where your instructor can review and grade your submissions.
To clone the repository, use the following Git command:
git clone <repository_url>
To stay organized, create a directory on your computer for this course and place all your assignment repositories inside it. After you’ve completed and pushed your work to GitHub, it will be safely stored in the cloud, and you can access it anytime from anywhere.
Use GitHub to submit your work. The following commands will help you do this:
git add .
git commit -m "add meaningful commit message"
git push
- If you are already on the department's Discord server, you will be added to the course's Discord channel
#document-engineering. - If not, join the department's Discord server before you can be added to the course's channel.
- During the first week, your name will be manually added to the class's Discord channel.
All materials provided in class will be accessible using the classDocs/ repository. Main site on GitHub: classDocs
All courses in the Department of Computer and Information Science are governed by the department’s policies on attendance, assignment submission, and the use of Artificial Intelligence (AI) tools. All of the policies described in this document do not supersede any policies in the Allegheny College Faculty Handbook, the Allegheny College Student Handbook, or the Allegheny College Academic Bulletin.
In the Allegheny College Department of Computer and Information Science (CIS), students are expected to come to class prepared, on time, and to stay engaged for the duration of the class period. This includes both class and lab sessions. This behavior is core to our shared departmental values and is in addition to the college’s attendance policy.
Coming to class prepared means coming with everything you need to engage in a class session. To satisfy basic expectations of CIS courses, this means, at minimum, that students must:
- arrive at class with a fully charged laptop
- bring their laptop charger or a battery back so as to ensure that their laptop works throughout the entire class session
- complete any pre-session work such as readings and preparatory assignments
The method of tracking attendance is at the professor’s discretion, and may include (but is not limited to) roll call, visually confirming student presence, and entrance/exit tickets.
One missed class or lab session counts as one absence. Coming to class/lab late, leaving early, or missing a large portion of a class/lab session will result in your being marked as “late” to class. Coming to class/lab unprepared may also result in being marked “late”. Being marked “late” to class three times during the course of a semester is equal to one absence.
Students can have a certain number of absences without any impact to their grade. These accommodations are meant to cover illness and emergency, so you should always come to class if you are able to do so.
The exact number of permitted absences may vary by course. As a general guideline, students cannot miss more than two weeks of class in total throughout the academic semester without receiving a letter grade reduction. For your course’s attendance policy, see the individual course syllabus.
The term “engagement” or our expectation that students remain “engaged” can mean many things, often varying by course. Baseline behaviors that indicate engagement include:
- participation in class activities and discussions
- defined contribution to class sessions in full-class or group discussions
- note-taking (physical or digital)
- participating in course session attendance requirements
- not participating in non-course related activities
- not completing non-course related projects
Tokens allow students to receive extensions or resubmissions on assignments, quizzes, and tests, with no questions asked by the course instructor except either in the rare cases of severe and/or extenuating circumstances or in cases that violate this policy document or any College-approved policy.
Students in the CIS department are expected to turn in assignments on time. “On time” means on or before the assignment’s due date. This means that an assignment cannot be turned in for credit after a due date, unless the student applies a token. Tokens must be applied via a Google Form at least 24 hours before the assignment deadline, with exceptions granted only for severe and/or extenuating circumstances.
The number of tokens a student is allotted varies by the course level and topic (e.g., 100-level courses receive the most tokens and 400-level courses receive the fewest tokens). Additionally, the length of extension granted by a token may vary by course or assignment. Some assignments may allow you to use a token for either a resubmission or an extension, whereas other assignments may only permit extensions.
| Course Level | Number of Tokens |
|---|---|
| 100 | 4 |
| 200 | 3 |
| 300 | 2 |
| 400 | 2 |
Tokens have specific windows where they are usable. In some cases, a token may be activated for the entire semester. In other cases, tokens may activate and expire during shorter windows, so that they are distributed throughout the semester, not all at once.
In special circumstances, professors may allow students to earn additional tokens by completing specific objectives. See your course’s syllabus for more details about its token policy.
An exception to the below: you should not come to class if you have a contagious illness like COVID-19, the flu, or a cold. If you have expended all your absences and tokens and are still sick with a contagious illness, you may contact your professor about options. If your symptoms are mild or you are recovering from a respiratory illness, we recommend that you wear a mask to class.
The accommodations provided by tokens and permitted absences are meant to cover extenuating circumstances like illness, emergency, and work. Professor must be informed of all athletic obligations at the beginning of the semester, or with as much notice as possible. If you are feeling healthy and well, you should make every effort to come to class on time and to complete assignments, rather than using absences and tokens you may need later.
These no-questions-asked accommodations are meant to protect student privacy, and to remove the additional effort of acquiring documentation under duress of illness or emergency. In addition, they allow the professor to remain focused on teaching rather than adjudicating excuses.
If extenuating circumstances are severe enough to require more absences and tokens, you may contact your professor to discuss options. In most cases, however, a situation of this gravity warrants a request for a “Late Drop” or “Incomplete” in the course, as the student will not have had adequate opportunity to learn the material.
CIS department faculty recognize that use of artificial intelligence (AI) tools such as Github Copilot, GPT, and Claude has emerged as a professional skill set in the knowledge and practices our coursework covers. Department faculty maintain a permissive attitude toward these tools by recognizing that you can and will use them. We do so considering the following position:
As a skill, using and correctly applying the results derived from AI tools is both context-based and discretion-worthy: these tools do not always provide correct or workable answers. Industry veterans and expert users run into many situations in which the responses these algorithms provide are plainly incorrect or unfit. In the context of department coursework, accepting an AI-generated answer wholesale or as a small part of an assignment may lead to less-than-satisfactory results in the context of both learning and deliverable quality.
As a learner, your time at Allegheny is meant to impart the knowledge that enables you to judge the fitness of a given approach, regardless of its origin. In the same way that CIS students employ compilers, integrated development environments, and refactoring tools, the use of an AI tool is not a substitute for developing the fundamental skills that develop this awareness. Importantly, research demonstrates that relying on generated responses reduces a learner’s ability to durably learn these lessons and skills, suggesting that you should cautiously embrace the use of AI when you complete CIS coursework [Chen et al., 2024].
In courses organized around fundamentals, instructors may prohibit students from using these tools or require students to use specific AI tools in order to teach the basic skills and concepts that students need to know to be successful in the field of CIS. Even in upper-level courses, assignments may feature requirements that decrease the applicability of a response generated with AI, thereby requiring you to thoughtfully consider the benefits, challenges, and fundamental limitations associated with the use of AI tools to generate content.
If you are able to use the output of AI tools in your assignments, be prepared to support their use in ways including but not limited to:
- citing instances where code has been generated and clearly defining the tools that generated them
- providing descriptive commentary (including prompts) around generated code either in in-line comments or assignment documentation
- considering improvements to the generated code, documenting specifics about your modifications and reasoning behind them
- revising the generated code or documentation so as to ensure that it is more suitable for the purposes of your assignment
Faculty do not intend these requirements as a “gotcha”; we assume the best of your effort. These guidelines follow industry best practices and prepare you for integrating current and future generations of these AI technologies into your computational practice.
Binglin Chen, Colleen M. Lewis, Matthew West, and Craig Zilles. 2024. Plagiarism in the Age of Generative AI: Cheating Method Change and Learning Loss in an Intro to CS Course. In Proceedings of the Eleventh ACM Conference on Learning @ Scale (L@S '24). Association for Computing Machinery, New York, NY, USA, 75–85. https://doi.org/10.1145/3657604.36620