Information About the Web Writing Style Guide Writing Sprint
As announced on the Computers and Writing and the Writing Spaces websites (CFP: The Writing Spaces Web Writing Style Guide Writing Sprint), Writing Spaces will be hosting a writing sprint to produce a manual of best practices for writing on the web for undergraduate writers. The schedule for the event is as follows:
Phase 1: Drafting (April 22-
May 2). Unconference participants are invited to drop in at anytime and add to the Google Doc containing the Web Writing Style Guide manuscript (the Google Doc URL will be announced April 22). The manuscript will be publicly available for editing; no login required.
Phase 2: Refinement & Review (
May 3-May 13May 9-May 14). At this time, editors will call for a “feature freeze” of the Google Doc manuscript (i.e. no more major additions or significant new content) so that everyone can begin discussing and refining the guide into a polished document. We'll use the new Google Docs discussion features to facilitate our review and refinement.
Phase 3: Copy Editing and Final Production (May 21-May 22). Unconference participants will be invited to provide final proofreading suggestions; the Writing Spaces editors will then complete the final production of HTML, PDF, and epub versions. If you have questions about the Web Writing Style Guide Sprint, contact us at firstname.lastname@example.org.
Important! Copyright and Licensing Permissions
The final version of this document will be released under a Creative Commons Attribution-NonCommercial-ShareAlike license. In contributing to the Writing Spaces Web Style Guide manuscript, you agree to have your contributions released under this license and to allow Writing Spaces and Parlor Press non-exclusive rights to publish digital and print versions of this document for sale. If you do not agree with the above, DO NOT contribute to the guide document.
Add Your Name as a Contributor
So that we can be sure to include you as an author, if you have contributed to this document, add your name and institution to the Contributors section at the end of the Writing Spaces Web Writing Style Guide manuscript so that you can be credited for your participation. If you have made contributions during Phase 1: Drafting (April 22-May 2), please also include your Google Doc username email address so we can make you an editor for Phase 2 & Phase 3 (the document will no longer be publicly available).
- Document design conventions. We’ll keep the visual design of this manuscript fairly simple (a) to make it easier to produce the three different formats at the end (HTML, PDF, and epub versions) and (b) to simplify collaboration on the text. Adopt the document design conventions you see in these instructions (except use the default Google Docs black text for headings).
- Working with visuals. Be careful how you select any visuals for inclusion in the text. Writing Spaces and Parlor Press must have clear rights (permission) to use them. For instance, we can’t use screenshots that have company or organizational logos in them because of trademark considerations. Also, the editors will need high quality visuals to use in the final versions; if you are creating your own visuals, you will need to provide a file version separate from what you embed in the Google Docs text (email it to email@example.com). Contact the editors if you have any questions about the visuals you want to include. Finally, be sure to include captions underneath any visuals.
- Hyperlinks. Integrate any in-text links using the Google Docs link insertion feature in the toolbar. Also, add a citation for the linked text in the References section at the end of the manuscript. This will assist those using print copies of the PDF version, while also providing a handy resource list.
Student Audience AddressThe primary audience for this guide will be undergraduate students. We have found during reviewing and editing of Writing Spaces: Readings on Writing that--because authors know that their fellow teachers will be reading their text--the teacher-as-author often unconsciously implements rhetorical strategies better suited for her fellow teachers as readers. With this guide, avoid unnecessary use of academic prose conventions in favor of producing a text with audience address that is much more like Steve Krug’s Don't Make Me Think: A Common Sense Approach to Web Usability or Janice Redish’s Letting Go of the Words: Writing Web Content that Works. As you write and revise the Writing Spaces Web Writing Style Guide manuscript, keep in mind the following considerations:
- Adopt the role of a helpful persona. Instead of coming across as a scholar or researcher, adopt more of the role of a fellow writer (albeit a knowledgeable one), who is writing as more of a coach or a mentor of the student reader in order to help them to become a better writer.
- Use a tone and voice well-suited for a student audience. The writing should probably be more informal in tone and style—even to the point of being colloquial—than your academic prose.
- Use student-situated examples and metaphors (and perhaps visuals) that will effectively communicate your ideas to students and also engage students with the concepts in the reading. You may need to rethink using examples from texts that we like to read as teachers.
- Use the right genre conventions. This is an instructional text where students will need less “defense” of the concepts than would otherwise be necessary in academic prose. They will need good explanations and examples to understand the concepts and advice on how to implement web writing best practices. Student readers will accept the concepts once they understand them and find them useful.
- Directly address the student audience. In the guide, beware of overtly talking about students in the third person. Talk directly to students. Use “you” to address them, much as you would during class. Use the imperative voice to be directive, to give instructions. In other instances, beware of where you might be referring to “students” when you should be talking about “writers.”
Consequently, DO NOT leave comments (in text or using the Google Doc comment feature) offering edits, suggestions, or critique. Feedback comments will be deleted by the editors during Phase 1. During Phase 2 will be the time for discussing the text (see below, Phase 2 Instructions). Save your teacher “feedback” mode for then, and during Phase 1, wear your writing hat exclusively. Prioritize finishing this version of the manuscript by implementing your ideas as ready-to-use prose, rather than offering your ideas as comments in the text meant for discussion or consideration by others. See yourself as part of team pushing a collaborative writing deadline in which there is no time for discussion, just drafting.
Contentious Best Practices and Style Rules: Offering Alternative TextIf you significantly disagree with the best practices or style rule principles offered in a particular passage--if you feel strongly that the text might be providing wrong advice to the writer--offer a new, alternative, highlighting the two different passages using the color background tool in the Google Docs toolbar. For example,
When a punctuation mark follows the end of a link, such as a comma or period, the punctuation should
be included in the link.
excluded from the link.
This will allow us to discuss the different view points during Phase 2: Refinement & Review and try to arrive at a consensus as to which version to use. Following the review period, Janice Walker, our content editor for the writing sprint, will evaluate the discussion and make the final call on what passages and best practices from the draft to include in the final version of the text.
Even so, since this is a writing sprint with a short writing, review, and production window, prioritize writing and revising existing text over creating alternative passages:
- If you can “live with” the advice being offered, avoid branching the manuscript.
- If you don’t agree with the advice being offered, but do not have alternative text to offer, leave it alone. You can suggest removing the passage during Phase 2: Refinement & Review.
- If you are offering an alternative view that you feel is better than what is currently written, but the existing passage is not necessarily wrong, then consider reworking the text to present both views.
- If you agree with the basic ideas, but simply don’t like the way that a style rule or best practice is presented in the text, then rewrite it.
- If you feel you can rectify the opposing ideas in two color passages, you can provide a third, alternative passage and color code it separately. Participants can discuss all three alternatives during Phase 2.
- If you revise any color coded sections that present alternatives, be certain to keep any changes color coded as well.
With Phase 2: Refinement & Review (May 3-May 13), the Writing Spaces editors are implementing a feature freeze, a convention from open source development projects, so that the community can produce a stable version by the end of the unconference. At this point, we are asking contributors of the writing sprint to restrict development of the text to more local paragraph and sentence level revision. We only have 11 days to get it ready for final copy editing. Thus,
- do not reorganize major sections of text
- do not add new sections of text
- do not introduce signfiicant new ideas
Work on refining the existing text. Help clarify existing explanations. Help smooth the voice and style of the text. Get us to a draft version that is ready for copy editing and final production (Phase 3). However, please limit offering feedback for revision. Make the revision changes you feel are necessary when they are likely to be uncontroversial.
That being said, the editors do welcome discussion of the validity and appropriateness of all the existing text, including the alternative passages created during Phase 1 (see above, Phase 1 Instructions). Add your "vote" of which alternative passages to keep by discussing them. And of course, if you feel like any other passage needs to be excluded from the final version, post a comment and explain why.
Gaining Access to the Google Doc
Unlike in Phase 1, the Web Writing Style Guide manuscript will no longer be publicly accessible during Phase 2. We need everyone logged in for engaging in discussion. The Writing Spaces editors will add everyone as editors to the Google Doc that included their name and Google Docs account email address in the list of contributors during Phase 1. If you were unable to participate in Phase 1 and would like to join in Phase 2, please send the Writing Space editors an email at firstname.lastname@example.org with your Google Docs account email address.
Join in on May 21 and May 22 for final copy editing of the manuscript. Add your corrects as comments to the manuscript. If you have not participated in Phase 1 or Phase 2, we'll need to give you access to the document. Please send the Writing Space editors an email at email@example.com with your Google Docs account email address.
Once the copy editing is complete, the Writing Spaces editors will work feverishly in an attempt to publish HTML, PDF, and epub versions by the end of the unconference.
If you have any questions that haven’t been answered here, don’t hesitate to contact us at Writing Spaces: firstname.lastname@example.org. Matt Barton, the Editor of the Web Writing Style Guide, will get back to you shortly.