{"id":154,"date":"2017-01-12T00:01:56","date_gmt":"2017-01-12T05:01:56","guid":{"rendered":"http:\/\/me.sites.mtu.edu\/meemscd\/?p=154"},"modified":"2022-09-06T10:44:50","modified_gmt":"2022-09-06T14:44:50","slug":"dg-getting-started","status":"publish","type":"post","link":"https:\/\/me.sites.mtu.edu\/meemscd\/dg-getting-started\/","title":{"rendered":"Doc-Prep Guidance \u2014 Getting Started"},"content":{"rendered":"

Heavily used in this course for documentation are Google Slides<\/em> and Google Docs<\/em>. \u00a0G-Slides<\/em> is used not only for conventional presentation slides, but also here for documents comprised of larger format 11\u00a0\u00d7 17 inch (ANSI B) sized pages we call a \u201cB-sheet.\u201d<\/p>\n

You will be provided with a team-specific template in one or the other (G-Slides<\/em> or G-Docs<\/em>) for each document, pre-meeting briefing, tech-memo, and cover letter you will have to produce.\u00a0 While one could download any of those templates as a Microsoft<\/em> (MS) PowerPoint<\/em> or Word<\/em> file to work with in that way, please do not do that.\u00a0 First, that actually introduces far more failure modes in regard to producing the final deliverable PDFs needed; it may not make sense now, but having seen literally over 1,000 docs generated that way, it is a fact here. \u00a0Second, and more important to you and your benefit, working in G-Slides<\/em> and G-Docs<\/em> comes with outstanding collaborative capability, something students have craved for a number of years and you now can benefit from since we have transitioned in 2022 from MS Office to Google Apps.\u00a0 That having been said, MS Excel<\/em> is used extensively as a tool called DP Manager; perhaps someday time will permit converting it to G-Sheets<\/em>.<\/p>\n

1\u00a0\u00a0\u00a0\u00a0 Formatting<\/h2>\n

For MEEM 4901 and 4911, prior to receiving the editable version of your team\u2019s team-specific templates your project title, customer name, team number, team members, etc. will be pre-filled for you in the appropriate and required places of the template.\u00a0 There is no need to alter any information on the cover page or in the headers with the exception of optionally adding a logo on the cover page as indicated in those templates that have a cover page.<\/p>\n

For G-Docs<\/em> templates, any areas where you will be adding content make use of the standard paragraph styles in G-Docs<\/em>\u00a0\u2014 Title, Subtitle, Heading 2 (Heading 1 not used), Heading 3, Heading 4, and Normal text\u00a0\u2014 already defined as desired including line spacing, indenting, and font types (Arial for headings, Times New Roman for non-heading text) and sizes.\u00a0 Do not change anything about these styles!\u00a0 And while not a matter of formatting, do not change the wording of the section headings; most section headings are tied to a grading rubric.<\/p>\n

A bit more on font types\u2026 Times New Roman is a \u201cserif\u201d font.\u00a0 That means it has little \u201cthingies\u201d called serifs at the ends of the letters.\u00a0 In contrast, san serif fonts like Arial do not have those \u201cthingies.\u201d\u00a0 Serif fonts are easier for the eye to follow in multi-line, textual format whereas san serif fonts are good for situations where resolution may be limited and\/or for short text elements like headings and bullet points of a line or two.<\/p>\n

Furthermore,<\/p>\n

<\/p>\n

That was repeated (word for word) so you can see the difference between the two fonts; it adds up by line height, not just line length.\u00a0 In any case, as noted, serif fonts like Times New Roman are easier for the eye to track across more than short phrases like section headings, titles, etc.<\/p>\n

To summarize, just stick to the noted styles in G-Docs<\/em> without changing them, and your formatting will be appropriate and as expected.<\/p>\n

<\/a>2\u00a0 \u00a0 \u00a0Graphics Annotations<\/h2>\n

A graphic (photo, illustration, CAD model, etc.) is generally much more effective if it is annotated to point the reader\u2019s attention to certain aspects of the graphic to which you are referring in the referencing\/accompanying text.\u00a0 Annotations are not optional here, they are expected\/required by us and will have a strong impact on your audiences well beyond your capstone design year.\u00a0 By the way, Arial (sans serif fonts) is good for figure annotations, which take the form of one to a few words.<\/p>\n

<\/a>3\u00a0 \u00a0 \u00a0Executive Summaries<\/h2>\n

Every document of length greater than about four to five pages should be summarized in an executive summary.\u00a0 In industry, the purpose of an executive summary is to brief the executive, manager, supervisor, etc., who may or may not read the entire document.\u00a0 Those on your Project Continuation Review panel at the end of Term-I may or may not read the full document in detail and often rely on your executive summary for a thorough yet concise summary of the document.\u00a0 Those on the SCD Advising Team will read your documents in their entirety!<\/p>\n

As you may be deducing, the executive summary is one of the most important parts of a technical document.\u00a0 It must stand alone and be concise while delivering enough detail to provide an accurate understanding of the status of your project.\u00a0 Stand-alone means it must be understood without having to leaf through the document.\u00a0 Do not refer to the body of the document (e.g., \u201cThis report contains objectives and constraints \u2026\u201d).\u00a0 An executive summary is also not<\/em><\/strong> a diary.\u00a0 It is not<\/em><\/strong> a discussion of \u201cwhat you did.\u201d\u00a0 It is a summary of the content of the document.\u00a0 Yes, the content mirrors what you did, but it is not to be described as what you did, rather what the content of the document is.\u00a0 For instance, do not write \u201cThe team determined the design requirements and divided them into constraints (having limits to which the solution must adhere) and objectives (having desired targets).\u00a0 They include\u2026\u201d\u00a0 Rather, write \u201cEngineering requirements include and constraints (having limits to which the solution must adhere) and objectives (having desired targets).\u00a0 They include\u2026\u201d<\/p>\n

This is offered as a basic example and is not<\/em> actual content we seek to be in your executive summary.<\/strong>\u00a0 You should assume in your executive summary and throughout your documentation that your audience knows generally what the design process is, what the design tools are, and why they are used.\u00a0 You need not<\/em> explain the \u201cwhat\u201d, \u201cwhy\u201d and \u201chow\u201d of the design process steps and tools.<\/strong><\/p>\n

Online doc-prep guidance will provide specifics for each document indicating an expected length and guidance on what content is expected.\u00a0 Guidance will begin with high specificity at the Problem Understanding Document (PUD) stage and taper off in specificity over the course of the project; you are expected to be learning with time and experience to gauge what content to cover in the later stages (and beyond capstone design into your career).<\/p>\n

Throughout all your documentation and other communication, you must realize that members of your audience outside the Capstone Design Program do not know what the various acronyms mean<\/strong>, such as PUD, TAD, and PPD.\u00a0 It is okay to use the acronyms, but only after introducing\/defining each; for instance, \u201cIn the attached Technical Archive Document (TAD)\u2026\u201d and then later you can write it as \u201cThe TAD illustrates that\u2026\u201d\u00a0 Though, introducing an acronym early on and then not using it until much later in the document is not very effective either.<\/p>\n

<\/a>4\u00a0 \u00a0 \u00a0References<\/h2>\n

Rather than numbering references sequentially relative to their order of appearance in the document, number them sequentially relative to when they are added into document; this is to avoid the non-value-added busy work of renumbering existing references when new references are added at a later date.\u00a0 Use the FML prefix as described in the doc-prep guidance for the Individual Research Document (IRD) assignment<\/a>.\u00a0 References that are brought in by more than one member of the team should use the prefix TEAM, i.e., [TEAM##].\u00a0 This is not a contest!\u00a0 The entirety of this approach, while being contradictory to the norm\/standard-practice of (non-prefixed) sequential numbering by order of appearance<\/strong>, is used here to minimize the risk of errors in reference numbering by significantly reducing the burden of reference number management<\/em><\/strong>.\u00a0 We break with convention for good reason\u00a0\u2014 to reduce the nonvalue-added burden on you so you can be more efficient in your work with less bookkeeping and error proofing.<\/p>\n

Formatting of the reference list is governed by the IEEE Citation style document<\/a>; this is a great, simple, efficient PDF document that gives many good examples (i.e., it teaches largely by example).<\/p>\n

Your reference list will be presented on one or more two-column page(s) in your Technical Archive Document (TAD), which is in the aforementioned B-sized (11\u00a0\u00d7 17 inch) format.\u00a0 Your team\u2019s initial references list will be compiled by merging references from all team members\u2019 Individual Research Document (IRD) assignment, which is also in the B-sized format and includes a references page for each individual to accumulate their references.\u00a0 Your references list in the TAD will be created at the Problem Understanding Document\/Review stage, and expanded from there throughout the course of the project.\u00a0 The references section of the TAD is after the final section of the body and before the Appendices; it is all set up for you in the TAD template you will receive soon.<\/p>\n

Doc-prep guidance will be provided throughout, as needed, to help you manage your reference list over the course of the project, correctly and efficiently.<\/p>\n

<\/a>5\u00a0 \u00a0 \u00a0Appendices<\/h2>\n

The number of appendices in your Technical Archive Document (TAD) depends on the needs of the audience.\u00a0 A number of appendices are mandatory and already set up in the TAD template.\u00a0 You may add appendices beyond those if you feel it is warranted; this is rare, but an option if it makes sense. \u00a0Specifically, Appendices A through E are reserved so you can start with F if needed.<\/p>\n

Regarding content, remember that an appendix is for information not required to understand the content of the main body of the document.\u00a0 Appendices are for supplemental information that may be useful for the reader desiring more detail.\u00a0 So, if it is a piece of information or graphic you think is important but not necessary to read or view in the main body of the document (in a textual portion or a B-sized \u201csummary\u201d page), then put it in the appendix and simply reference it in the main body of the document (e.g., \u201cAdditional background information on material properties of options considered is presented in Appendix XX\u201d).<\/p>\n

Do not just do a data-dump in the appendices.\u00a0 No one needs to see every piece of MATLAB<\/em> code, for example.\u00a0 Additionally, each appendix must be clearly labeled at the top of the pages; this is already done for you in Appendices A through E in the TAD template to be provided.<\/p>\n

 <\/p>\n

<\/a>6\u00a0 \u00a0 \u00a0The Storyline \u2014 Saving the Most Important for Last!<\/h2>\n

It is important to see the entirety of your reporting as telling a story. \u00a0Not that your writing is story-like (with the exception of the narratives related to current situation and future vision, which are told in a story-like fashion).\u00a0 The \u201cstoryline\u201d is a flow of information throughout the documentation; it represents your line of thought as you work through the work you are presenting\u00a0\u2014 your work-product.\u00a0 Remember, the reader is generally someone who is not as close to the project as you are.\u00a0 You will be living and breathing this work on a daily basis.\u00a0 Your reader is living and breathing other things.\u00a0 He\/she is busy too.\u00a0 Making the reader\u2019s life easier is always good for your cause.\u00a0 And remember also, most of your readers will be viewing this in a future where you are not available to answer their questions or to provide clarifications.\u00a0 This is important in any forms of your documentation and reporting, in particular the TAD as described below.<\/p>\n

One key element of maintaining the storyline is the presence of \u201cinputs\u201d and \u201coutputs\u201d text boxes on many of the TAD pages.\u00a0 The Page Input<\/em><\/strong> helps the reader center their mind on the new topic at hand (for that page) and reminds him\/her of the information that flowed into the work that generated the information on that page.\u00a0 This is important even if it flows from the immediately previous page; often<\/strong> this is not<\/em><\/strong> the case, though, as the design process is not purely serial.\u00a0 It is easy for someone to lose the storyline without some help from the author\u00a0\u2014 you.<\/p>\n

The Page Output<\/em><\/strong> provides information to \u201cwrap-up\u201d the work presented on that page.\u00a0 It can be conclusions, decisions (which are different than conclusions), or simply \u201cwhere next.\u201d\u00a0 Where next is generally always an element of a page output textbox.\u00a0 It indicates where this information is next used and for what and\/or how it will be used.\u00a0 In a sense, it is the start of a virtual bridge that leads to the input textbox somewhere else in the document.<\/p>\n

Hopefully you can see the logic in the following requirement: the Page Input<\/em> textbox should be at the top left of the page and the Page Output<\/em> textbox should be at the bottom right of the page (if at all possible; move elsewhere, if necessary, still preferably at the bottom somewhere).\u00a0 How you lay out the other information on a B-sized page is up to you.\u00a0 The examples provided in the templates are simply examples.\u00a0 Depending on the relative sizes of tables, illustrations, etc., rearranging your content relative to the examples may be needed.\u00a0 One exception is the requirement noted in regard to the Page Input<\/em> and Page Output<\/em> textboxes.<\/p>\n

\n

Google Docs<\/sub><\/em>, Google Slides<\/em>, and Google Sheets<\/em> are trademarks of Google LLC.
\nMicrosoft<\/em> and Excel<\/em> are trademarks or registered trademarks of Microsoft Corporation.
\nMATLAB<\/em> is a registered trademark of The MathWorks, Inc.<\/sub><\/p>\n\n\n\n
\u00a9 2017, William J. Endres<\/td>\nUpdated August 28, 2022<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n","protected":false},"excerpt":{"rendered":"

Heavily used in this course for documentation are Google Slides and Google Docs. \u00a0G-Slides is used not only for conventional presentation slides, but also here for documents comprised of larger format 11\u00a0\u00d7 17 inch (ANSI B) sized pages we call a \u201cB-sheet.\u201d You will be provided with a team-specific template in one or the other […]<\/p>\n","protected":false},"author":35,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[17],"tags":[],"_links":{"self":[{"href":"https:\/\/me.sites.mtu.edu\/meemscd\/wp-json\/wp\/v2\/posts\/154"}],"collection":[{"href":"https:\/\/me.sites.mtu.edu\/meemscd\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/me.sites.mtu.edu\/meemscd\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/me.sites.mtu.edu\/meemscd\/wp-json\/wp\/v2\/users\/35"}],"replies":[{"embeddable":true,"href":"https:\/\/me.sites.mtu.edu\/meemscd\/wp-json\/wp\/v2\/comments?post=154"}],"version-history":[{"count":40,"href":"https:\/\/me.sites.mtu.edu\/meemscd\/wp-json\/wp\/v2\/posts\/154\/revisions"}],"predecessor-version":[{"id":2668,"href":"https:\/\/me.sites.mtu.edu\/meemscd\/wp-json\/wp\/v2\/posts\/154\/revisions\/2668"}],"wp:attachment":[{"href":"https:\/\/me.sites.mtu.edu\/meemscd\/wp-json\/wp\/v2\/media?parent=154"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/me.sites.mtu.edu\/meemscd\/wp-json\/wp\/v2\/categories?post=154"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/me.sites.mtu.edu\/meemscd\/wp-json\/wp\/v2\/tags?post=154"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}