Project

General

Profile

Knowledge Base »

Technical Writing

Guidelines

Students should consult these guidelines for preparation of their reports:
  1. RPI_Technical_Writing_Manual.ppt
  2. Tips_for_Writing_a_Technical_Report.docx
  3. export:training/A+Practical+Guide+toAcademic+Writing+updated.pdf (although written for international students, this is valuable for all!)

Students are recommended to work with the Center for Global Communication+Design ( COMM+D ) for written and oral presentation assistance. See the page for more information.

This is a great resource to help with your communication skills.

Helpful Hints for Technical Writing, e.g. Reports

Use these hints for your Capstone design reports and the professional workplace.

Be specific.

Use clear, concise wording that conveys meaning. Avoid use of vague words.
(e.g., better? improved? What is meant by better/improved? – faster, less expensive, easily implemented? Use those descriptive words instead.) What is the key message for the reader?

Background Information

Clarify technologies and items that may not be the expertise of all readers, especially those unfamiliar with your project work. Consider your boss’ boss. Would he/she understand what you’ve written without any prior exposure to your project or the technology?

Figures and Schematics

Use figures or schematics to help explain key concepts – “a picture IS worth a thousand words”. Always include a marker or scale in every photo. This allows the reader to determine the size of the object (e.g., 1 cm or 1 m?) Provide an explanation of the figure in the text, in addition to the Figure caption, and refer to the Figure by number (e.g., “Figure 3 shows a representative….” What do you want the reader to know about the Figure? What is the key takeaway?)

Tables

Use bulleted lists or tables to summarize key points. This makes it easier for the reader. The reader can scan the list/table without searching the text for key points. Provide some explanation of the data in the text and refer to the table by number. (e.g., “Table 4 provides a comparison of X and Y, and ….” What do you want the reader to know from the Table?)

Graphs and Plots

Ensure all plots are labelled, including labels on both axes. Include a ledger to identify different data sets. If multiple plots will be used for comparison, use a similar scale for each plots to allow the reader to more readily compare.

References and Attribution

Use references and cite them in the text with a numbered reference from the Reference List. Any information, including pictures, figures, tables, schematics) utilized from another source must be cited. Otherwise, it is plagiarism. This is unacceptable in all professions.

Acronyms

Use of common acronyms is acceptable. For the first occurrence in the report, use the full description followed by the acronym (e.g., printed circuit board (PCB)).
Less common acronyms should be described in the Glossary section.

Font/Formatting

Maintain the same font and formatting throughout the entire report.

Possessives

Possessives are not used in technical documentation, and not with inanimate objects
(e.g., the data’s, the semester’s)

Writing an Abstract

Please consult COMM+D if needed for guidance on how to write an abstract.
For additional information, please use your favorite internet search engine to look for: "What is an abstract"

The Design Process

For teams struggling with evaluation matrices and concept generation / selection refer to your IED textbook. Sections from "Product Design and Development" by Ulrich & Eppinger can be found here.

Work Breakdown Structures

These are covered on a separate page.

Meeting Minutes

Taking good meeting minutes and posting them as plain text makes it simple for team members to find information and decisions. Hints and suggestions have been collected here.

Design Document Tips

  • Remove all internal team comments and accept all changes in the version you submit to CE for grading or to your client for review!
  • Cover page should be only 1 page! Adjust formatting to fit ALL names on a cover sheet! Teams are blindly using the template and spanning two pages with the list of names.
  • The section on engineering standards - it is NOT acceptable to reproduce, in their entirety, any copyrighted standard - and they ALL are. Cite them. But explain, specifically, how they affect your project, what requirements you added based on them and how you are addressing them. Do NOT just list them!
  • Break your project plan up by milestone and EXPLAIN your schedule. If anything is 'red' you must explain why that is so and what the team will do to address it. Your Gantt chart at midterm MUST adhere to the guidelines found in the Capstone Support wiki!
  • Update the Table of contents, list of figures and list of tables before submitting! They sometimes contain numbering errors or incorrect page numbers from earlier updates.
  • If a table spans multiple pages you must repeat the headings. Word will do this for you - automatically - if you tell it to. And you must!
  • Executive summary should encourage a busy executive to read your entire report. It should summarize your >report< especially your accomplishments. The executive summary should not primarily cover the project's history. Too many reports have only 1 paragraph at the end that mentions the current semester. It would not cause a busy executive to take time to read the report.
  • Alphabetically sort the Terms & Abbreviations section.
  • Use numbered sections/subsections - as in the template.

Microsoft Office

Microsoft Word for Technical Reports

Some time saver tips for simplifying your final report preparing are included in the attached PowerPoint file. MS_Word_Tips.pptx

Avoid having a table's row break across a page. For Word, this can be stopped using this tip found at http://www.lockergnome.com/windows/2007/09/21/prevent-table-rows-from-breaking-across-pages-in-word/

  • Select the appropriate table.
  • From the Table menu, click Table Properties.
  • Click the Row tab.
  • Uncheck the 'Allow row to break across pages' option.

Equation Editor

Office 365

Office 365 and OneDrive @ RPI provides an overview for RPI students.

A web browser version provides a subset of features. For more information, see Differences between using a document in the browser and in Word

Master Document and Subdocuments

MS Word allows authors to combine chapters files and create a single document. Some tutorial materials are as follows.

It is not easy to combine references, and there are two solutions.

Creating and Using Equations

The Linear Format method is significantly faster to enter equations than the GUI method. However, it requires you to memorize TeX-like commands. For details, see Typing Equations via Linear Format

The commands are found in the "Math Autocorrect" tab in the Equation Options.

Comparing and Merging Microsoft Office Documents

This information can be found on this page: Comparing and Merging Microsoft Office Documents

If you manually merge two Word files, such as cut and paste a section from a document to the other file, citations are also copied. You need to update the bibliography (references) by pressing F9 or using the Update Field option.

Embedding Slides or Spreadsheets into other Documents

When inserting PowerPoint slides or spreadsheet results into presentations or Word documents, DO NOT paste them in as images. It is almost always better to embed the Excel or PowerPoint source into the destination document (Word or other PowerPoint presentation). If you paste in an image of the spreadsheet or slide then it cannot be revised unless the original separate spreadsheet or PowerPoint can be found. This often causes challenges for teams as that document has proven to be difficult to find! Sometimes the original was never posted to EDN and is lost. To make a revision the spreadsheet or slide must be recreated from scratch, a great loss of productivity. For spreadsheets, the formulas used may be lost forever.

If the original document is embedded then it is possible to simply double click on it. That will open it up for editing so that the revision(s) can be made. When the document is saved, the edits will be saved as well. Additional edits can still be made at a later date.

Embed, do not paste!

Citation Tools

ATTACHMENTS BELOW