ACM SIGDOC Structured Authoring Committee Resources

Style & Authoring

This page provides support for content developers and reviewers. If you have interest in developing content about one of these subjects or some other subject that interests you, please send your contact information and a description of your interest to [email protected]. We need and value your support.

ACM SIGDOC Structured Authoring Style Guide

Between the style prevalent in industry technical communication and the style prevalent in academic journals, there is little commonality. We trust that academic instructors will continue to teach students how to write term papers, theses, and dissertations in the academic style. Our committee adds no value there. We can, however, provide future technical communicators with a very basic style guide aligned with many industry style conventions. Each industry company develops and maintains a style guide for its technical communicators and UI designers. Our own committee content developers hail from different companies, so we needed to develop a lowest-common-denominator style guide for our own writing.

As with all our committee resources, instructors are welcome to download and customize this style guide for curriculum use. If you have interest in contributing to this lightweight style guide please contact our editors Emily Gresbrink and Scot Marvin.

Style issue	Usage
Code - block	a - Format in monospace font one point size smaller than running text. b - Format line breaks so as to preserve the code to copy and paste. c - (Ideally) Upload to our GitHub repo complete, ready to run examples. d - Link to the example set on GitHub.

Code - inline	a - Format in monospace font one point size smaller than running text.

Names - acronyms	a - Full name with acronym in parenthesis (first mention). b - Acronym (thereafter).

Names - author(s)	a - Place the full name and degree immediately following publication title. b - Place the affiliation immediately following author name (optional).

Names - elements or attributes	a - Format in monospace font one point size smaller than running text. b - Avoid plural forms.

Names - files	a - Format in monospace font one point size smaller than running text.

Names - products	a - Company and product name (first mention), e.g. Syncro Soft Oxygen Editor. b - Product name (thereafter). e.g. Oxygen.

Names - standards	a - Standards org and standard name (first mention), e.g. OASIS DocBook. b - Product name (thereafter), e.g. DocBook.

Names - user interface elements	a - Bold.

Names - variable attribute values	a - Italics

Ordered lists	a - Strive for a consistent sentence structure for each list item, e.g. Context - Ver b - Object - Goal. b - Separate actions (list items) from effects and examples (blocks nested within list items. c - Provide at least a one-sentence introduction preceding the list. Recommended.

Person	a - Choose industry "you perspective" whenever possible.

Section - Document history	a - Provide a brief table documenting the change history (optional).

Section - Further reading	a - Provide toward the end a list of further reading resources with liks.

Section - Guidepost	a - Provide a brief overview of the goal of this resource and learning objectives.

Section - Pre-requisites	a - Provide an unordered list of skills required for the reader to make sense of the content.

Section - Terminology	a - Provide a brief list terms and definitions if there are many that cannot be defined in unning text.

Tables	a - Avoid more than five (5) columns. b - Precede with a brief introduction or caption. c - Avoid images within cells. d - Avoid tables nested within tables.

Titles	a - What is XXX? (Concepts). b - How do I use XXX? (Tutorials). c - Best practices for XXX (Best practices).

Tone	a - Choose conversational without being overly familiar or folksy.

Unordered lists	a - Nest no deeper than three levels total. b - Maintain parallel sentence structures. c - Terminate each list item with a period. d - Provide at least a one-sentence introduction preceding the list. Recommended.

Voice	a - Choose active voice whenever possible (nearly always).

Roles for reviewers

Professional organizations such as ACM, IEEE, W3C, and OASIS rely upon a process for peer review. In its Information for Authors and ACM Policy on Authorship statements, ACM reiterates the importance of professional integrity for both the authors and peer reviewers of its journal publications. Our committee on structured authoring provides content and sample code for curriculum learning resources instead of journal articles. Our committee would like to maintain the ACM spirit of professional integrity as it applies to our content and charter.

All our committee resources go through the equivalent of a journal peer review process. Each resource is reviewed from the perspective of editorial integrity, technical integrity, and instructional integrity. There can be overlap between reviewers, to be sure, but we do our best to assign, track, and complete each type of review befor a resource gets posted to our Curriculum Resources library. This section documents the current roles for each type of reviewer.

We track the status of each phase in the review process on our committee dashboard.

Role	Contributions
Industry author	Industry authors can work in any source format that is comfortable for them. By default, many authors work in gDoc or MS Word formats because it is easy to move that content into gDoc format for review. Authors are responsible for the following: Review the style/editorial guidelines. Draft your resource. Tip: If you are drafting your resource in gDoc format, feel free to author it in our gDrive folder named Folder - DRAFT - Resources. When you are ready to begin the review process, move or copy/paste your resource content into a gDoc in the gDrive folder named Folder - REVIEW - Resources. Notify the Chair and contact TBD/Editor to schedule reviewers and milestones. Work through the review process. When reviews are complete, notify the Chair and move your completed gDoc to Folder - POSTED - Resources The Infrastructure team will handle posting to our web site and creating parallel formats for you.
Technical editor	Our committee produces resources about structured content for curriculum instructors, researchers, and students. Unlike traditional industry publications, our resources are open source and intended to be modified by individual instructors before integration with their curriculum materials. Achieving 100% editorial or formatting consistency across our resources is not a goal. The benefit of having an editorial pass through new resources is one of internal efficiency. Once the author and editor agree that the new resource conforms to our no-frills, baseline style guide, subsequent technical and instructional reviewers should disregard editorial issues to focus on technical and instructional issues respectively. When contacted by the author or Chair, negotiate milestones for the editorial review. Collaborate with the author toward the completion of the editorial review. When the editorial review is complete, confirm status with the author and notify the Chair to recruit subsequent technical and instructional reviewers. Update the no-frills style guide as appropriate.
Technical reviewer	Technical reviewers are industry folks who are familiar with both the technology and its deployment relevant to a particular resource. Technical reviewers engage after the editorial review and before the instructional review. Technical reviewers identify any technical errors or ambiguities in the resource being reviewed and (within reason) suggest items worth adding to the resource. Removing content or completely reorganizing content is not a goal. If an instructor does not believe that a section is not relevant to her/his class, the instructor can remove it. When contacted by Chair, negotiate milestones for completing the technical review. Collaborate with the author toward the completion of the technical review. When the technical review is complete, confirm status with the author and notify the Chair to recruit subsequent reviewers.
Instructional reviewer	Instructional reviewers are college instructors or program administrators who have experience with or interest in structured content. The instructions review happens after the editorial and technical reviews. The instructional review is intended to identify sections of a resource that require additional explanation or exemplification. Removing content or completely reorganizing content is not a goal. If an instructor does not believe that a section is not relevant to her/his class, the instructor can remove it. When contacted by Chair, negotiate milestones for completing the instructional review. Collaborate with the author toward the completion of the instructional review. When the instructional review is complete, confirm status with the author and notify the Chair to move the resource from REVIEW to POSTED status. Share with authors, editors, and technical reviewers any best practices that would enhance the relevance of our resources.