Welcome to ENGL 396: Software Documentation!
ENGL 396 is a 5-credit writing course that teaches you how to create, edit, and maintain technical documentation that supports software end users and software developers. Document types studied in the course include conceptual overviews, instructions and tutorials, code samples and code comments, release notes, best practices documents, FAQs, and API references.
You will build digital literacy by working with tools and concepts used in the production of software documentation, that may include but is not limited to HTML, CSS, markdown, autogenerated documentation tools, and source control software. You will also build critical literacy in the software documentation genre by questioning the notion that software documentation is neutral and by analyzing software documentation for bias and power dynamics. The course fulfills either a W or a C general requirement.
Who This Class Is For
This course is designed for students who are interested in careers in technical communication—a field in which many jobs are software related—and students interested in working in careers in the software industry, including software engineers, program managers, and other technical roles. The course is also for anyone who is curious about software documentation and who wants to practice writing clearly and concisely about technical topics.
The content of this course is more technical in nature than many other writing courses at the University of Washington and includes detailed study of software, including reading code with the help of comments and understanding software architecture, including the integration of software frontends and backends. While you do not need formal programming experience to succeed in the course, familiarity with software concepts and at least one programming language is highly recommended.
Learning Objectives
You will learn how to:
- Write a variety of forms of software documentation, including conceptual content, task-based information, and reference documentation.
- Analyze the needs of different audiences, particularly software end-user audiences and software developer audiences, and write for these audiences.
- Research specific software applications by reading code and code comments and interviewing subject matter experts.
- Write software documentation that adheres to software industry style standards, such as the Microsoft Style Guide.
- Author, publish, and maintain software documentation using key technologies and concepts, such as HTML, CSS, markdown, topic-based authoring, DITA XML, source control, and single-sourced content.
- Write for internationalization and translation, and design and write accessible documentation.
- Identify ethical concerns in technical documentation and employ ethical best practices.
Professor
Name: Chris Holstrom
Preferred Name: Please just call me "Chris." If you want to be formal, call me "Dr. Holstrom."
Pronouns: He/Him/His
Email: cholstro@uw.edu
Office: Padelford A-21
Office Hours: Mon & Wed 10:00-11:00, and by appointment
Webpage: My English Department Profile Page
Communication
Communication is critical to your success in this course. I am here to help you! I want to hear what's important to you, when you need help, when you have a question, and when you want to discuss an idea. Just let me know.
Don't wait until a small problem becomes a big one--communicate right away. For example, if you know ahead of time that you will need extra time for an assignment, let me know and we'll come up with a plan together.
Here are the main communication channels for this course:
- Office hours (Mon & Wed 10:00-11:00, and by appointment): You can use this time for anything that you need to discuss.
- Email (cholstro@uw.edu): Email is my preferred form of written communication. I will reply to email within 24 hours on weekdays. If for some reason I do not, please reply to your email thread with a message like: "Just putting this back at the top of your inbox." Make sure that your email has a title with the course number in it ("ENGL 396: [descriptive title]") and a clear description of your problem or question.
- Canvas Announcements: I will use Canvas announcements to send updates to the whole class. It is your responsibility to monitor your UW email address and Canvas on a regular basis.
Required Course Materials
Laptop or Tablet: Bring a laptop (or at least a tablet) to each class session, so you can write and edit, participate in activities, and access Canvas.
Textbook: We will read selected chapters and sections from Developing Quality Technical Information by Carey et al. This book was written by the editors that I worked with at IBM's Silicon Valley Lab, and it is a great guide to writing software documentation. You can buy a copy of the book if you like (I recommend it!), but I will provide PDFs of the assigned readings from the third edition.
Additional Readings: I will provide PDFs and links for additional readings. See the Modules to find the readings that are due before each class session.
Software: You'll work with some example software that is written in R, and you'll generate reference documentation using the package roxygen2. To do this work, you'll need to install R and Rstudio.
GitHub Account: You'll store, edit, and publish documentation for this class on GitHub. If you have an existing account, you can use that account and create a repo for ENGL 396. If you do not have an account, you can create one for free.
Assignments
The assignments in this course are designed to help you think about key topics in technical and professional editing, to get practice editing and revising a variety of documents, and to communicate style standards in a clear and thoughtful way.
Listed below are the types of assignments in this class and how much they count toward your grade. You can see the details about the assignments on the assignments page.
- Annotating Class Readings (10%): For many class readings, you will submit at least three annotations or responses using Hypothesis in Canvas. Each reading is worth 1 point. There are 12 readings to annotate, but only 10 readings will count toward your grade--your two lowest scores will be thrown out. Annotations and responses are due before class because we will use them as a basis for class discussion.
- Completing In-Class Activities (39%): Almost all of our class sessions will have hands-on activities that you will do in small groups, discuss with the rest of the class, and turn in on Canvas. Each activity is worth 3 points. There are 16 in-class activities, but only 13 activities will count toward your grade--your two lowest scores will be thrown out. You can receive up to 1.5 points per activity if you miss class and complete an activity on your own.
- Planning, Writing, Editing, and Publishing a Doc Set (51%): The bulk of the class focuses on a series of assignments that guide you toward publishing a document set about a piece of software. In this assignment sequence, you will write a doc plan, conceptual overview, task information, and reference information. You will edit your drafts and publish a polished doc set on GitHub. You will also reflect on your writing process as part of this assignment sequence.
There are no tests or quizzes in this course.
Grading
The overarching grading policy for this class is to reward effort and engagement, and to not penalize you for small mistakes. If you put in the work on an assignment and engage deeply in the material, you will get a good grade--even if you make some mistakes or don't know a specific grammar or formatting rule. If you put in less effort and connect with just the surface of the assignments, you will get a lower grade.
Each assignment (other than in-class activities and reading annotations, which are graded entirely on completion) has a grading rubric. Your grade for the course overall is calculated based on the following mapping. You can view your calculated grade in Canvas.
Grade on 4.0 Scale | Percentage Cut-off |
4.0 | 98% |
3.9 | 96% |
3.8 | 94.5% |
3.7 | 93% |
3.6 | 91% |
3.5 | 89.5% |
etc. |
Late Assignments: Late assignments are accepted, but will receive a reduced grade in line with how late the assignment is and any mitigating factors. To minimize point reductions (often to no reduction at all), let me know ahead of time if something will be late. I will work with you to make sure that you don't fall too far behind.
Grade Clarifications and Resubmissions: You may ask for clarification about or contest any assignment grade that you receive. You can also resubmit assignments if you are not satisfied with your grade and want to improve your score. Resubmissions must include a short summary of the changes that you made from the previous submission.
Due Dates: In-class activities and peer reviews are due by the end of the day that they happen in class. Other assignments are typically due the day before class at 11:59pm. Because we have a Monday class, many assignments have a listed due date of Sunday. My intention is not for you to have due dates on the weekend. I've just heard from students in the past that they want all dues dates in Canvas at the same time of day (i.e. 11:59pm and not the morning before class). If you turn in "Sunday" assignments by Monday before class, they won't be late and you don't need to let me know ahead of time.
Student Responsibilities
As with anything that you do, the more that you put into this course, the more you will get out of it. Your responsibility is not to be a great writer. Your responsibility is to put in the work to become a better editor.
That work includes:
- Attending class regularly, being as mentally present as you can be, and actively participating in in-class activities.
- Letting me know if you need extra help, extra time, or an extra explanation of a difficult concept. I'm here to help, but I can't do that if you don't let me know what you need.
- Critiquing and editing others' writing honestly, respectfully, and with the goal of helping to improve their writing.
- Reading and annotating documents--both your own and others'--to better understand what makes a document work.
- Supporting your classmates and helping to make this class a safe and comfortable place, including during class presentations.
- Trusting that you can improve your software documentation skills through practice and study.
If you do this work while treating yourself and the rest of the class with respect, you will do well.
Writing and Editing Resources
This is an editing course, and writing and editing go hand-in-hand. Here are some resources that might help you with the class.
- Purdue Online Writing Lab (OWL) is an online resource with a wealth of information about writing and editing. You'll find many websites with answers to your writing questions, but I've found that this site is consistently one of the best places to look.
- The Odegaard Writing & Research Center (OWRC) offers free, one-to-one, 45-minute tutoring sessions for undergraduate, graduate, and professional writers in all fields at the UW. They will work with writers on any writing or research project, as well as personal projects such as applications or personal statements. Their tutors and librarians collaborate with writers at any stage of the writing and research process, from brainstorming and identifying sources to drafting and making final revisions. For more information or to schedule an appointment, see their website.
- CLUE Tutoring is more than a resource you can access when you're struggling in a class; it's a welcoming, inclusive space for students to connect, ask questions about various subjects, prepare for exams, and have support on homework.
- The Microsoft Writing Style Guide, Google developer documentation style guide, Red Hat supplementary style guide for product documentation, Salesforce Style Guide for Documentation and User Interface Text, and Apple Style Guide are all useful references for industry-standard software documentation style.
Academic Integrity
The University of Washington takes academic integrity very seriously. Behaving with integrity is part of your responsibility to the shared learning community. If you’re uncertain about if something is academic misconduct, just ask. I am willing to discuss any questions that you might have.
The type of academic misconduct that is most relevant to this course is plagiarism. Plagiarism can take multiple forms:
- Presenting someone else's work (or an AI's work) as your own. For example, buying an assignment online or from another student, using an article that you find online as your own, or asking ChatGPT to write your paper or part of your paper. This form of plagiarism is antithetical to the goals of the course and, frankly, unproductive because you will not be graded on how polished your assignment is but how engaged you are in the process of improving it.
- Presenting part of someone's work as your own without properly quoting and citing. You can quote directly from other sources or summarize their ideas, but you must cite them properly and not present the writing as your own.
- Patchwriting or failing to write in your own words. Patchwriting is similar to paraphrasing or summarizing, but the writing that you produce is too similar to the original document to be considered your own writing. Patchwriting is often unintentional and is common for students learning to write in a new genre.
Assignments will have SimCheck plagiarism detection enabled. Concerns about plagiarism or other behaviors prohibited by the Student Conduct Code may be referred for investigation and adjudication. Students found to have engaged in academic misconduct may receive a zero on the assignment (or other possible outcome).
Anti-Racist Pedagogy
I am committed to engaging with anti-racist pedagogies. These pedagogies may take various forms, such as curricular attention to voices, communities, and perspectives that have been historically marginalized inside and beyond academic disciplines; inclusive classroom practices; discussions of racism; and consideration of other forms of prejudice and exclusion. I believe that countering the cultures and practices of racism in an academic institution is fundamental to developing a vibrant intellectual community. If you’re interested in how teachers of English as a professional community have taken up anti-racist work, check out the National Council of Teachers of English Statement on Anti-Racism to Support Teaching and Learning.
Religious Accommodations
I am committed to engaging with and supporting religious students, including accommodation of student absences or significant hardship due to reasons of faith or conscience, or for organized religious activities. The UW’s policy, including more information about how to request an accommodation, is available at Religious Accommodations Policy. Accommodations must be requested within the first two weeks of this course using the Religious Accommodations Request form.
Accessibility Accommodations
Your experience in this class is important to me. It is the policy and practice of the University of Washington to create inclusive and accessible learning environments consistent with federal and state law. If you have already established accommodations with Disability Resources for Students (DRS), please activate your accommodations via myDRS so we can discuss how they will be implemented in this course.
If you have not yet established services through DRS, but have a temporary health condition or permanent disability that requires accommodations (conditions include but not limited to; mental health, attention-related, learning, vision, hearing, physical or health impacts), contact DRS directly to set up an Access Plan. DRS facilitates the interactive process that establishes reasonable accommodations. Contact DRS at disability.uw.edu.