{"id":610,"date":"2014-11-24T11:22:37","date_gmt":"2014-11-24T18:22:37","guid":{"rendered":"https:\/\/blogs.ubc.ca\/coetoolbox\/?page_id=610"},"modified":"2018-03-28T14:32:19","modified_gmt":"2018-03-28T21:32:19","slug":"project-documentation","status":"publish","type":"page","link":"https:\/\/blogs.ubc.ca\/coetoolbox\/industry-project-guidelines\/project-documentation\/","title":{"rendered":"Documentation and Reporting"},"content":{"rendered":"<p><img loading=\"lazy\" decoding=\"async\" class=\"alignright\" src=\"http:\/\/www.sauder.ubc.ca\/Faculty\/Research_Centres\/Centre_for_Operations_Excellence\/%7E\/media\/E3B2C2CA6724416E883DF72CC1093A0E.ashx\" alt=\"\" width=\"100\" height=\"99\" \/>It\u2019s important that your work be reproducible. The best way of making that happen is to produce scripts that automatically perform all of the steps in your analysis\u2014data cleaning, merging, plotting, statistical analysis\u2026. These scripts won\u2019t be the same as the logs (written or digital) of all of the things you tried along the way; they\u2019ll be much tidier! The ideal is to have different folders containing (1) your raw data files, unedited, (2) all of the analysis scripts (3) all of the processed\/cleaned data fields generated by your scripts.<\/p>\n<h1>Reporting Timeframe<\/h1>\n<p>You\u2019ll also need to deliver a report on your work to your client. The deadline for a complete draft of this report is August 13, 2018.<\/p>\n<p>Working towards these goals, each month you\u2019ll need to deliver sections of your report and documentation. Work with your PA to establish a timeline. It might look like:<\/p>\n<ul>\n<li>May 18, 2018:\n<ul>\n<li>Literature review complete and submitted to your PA. (This date is firm and applies to all teams.)<\/li>\n<\/ul>\n<\/li>\n<li>June 8:\n<ul>\n<li>First draft of introduction and methods section of report<\/li>\n<li>Data cleaning complete, including scripts, raw and tidy data, and explanatory documentation<\/li>\n<\/ul>\n<\/li>\n<li>June 29:\n<ul>\n<li>Exploratory analysis complete, including scripts, graphs, and documentation<\/li>\n<li>Model-building complete, including documentation<\/li>\n<\/ul>\n<\/li>\n<li>August 3:\n<ul>\n<li>First draft of conclusions section; identify whether materials from previous months should go in the body of the report or in appendices.<\/li>\n<li>Scenario-testing complete<\/li>\n<\/ul>\n<\/li>\n<li>August 10:\n<ul>\n<li>Poster and 1-pager draft submitted to PA for review<\/li>\n<\/ul>\n<\/li>\n<li>August 17:\n<ul>\n<li>Poster and 1-pager submitted to client for their approval<\/li>\n<li>Full project report draft complete, including executive summary and conclusions<\/li>\n<\/ul>\n<\/li>\n<li>August 31:\n<ul>\n<li>All materials complete; poster and 1-pager approved by client<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<h1>Project Shared Folder<\/h1>\n<p>To make sure that you and the current project team, as well as anyone who is working on the project in the future,\u00a0know where to find documents, it&#8217;s important to have a well-organized shared folder. Don&#8217;t store anything\u00a0on local machines (on your desktop or the C: drive); doing so can present a security risk and slow down your computer.<\/p>\n<p>Below is an example of how to structure a shared folder and the typical contents of the sub-folders. Minor variations may be appropriate for your project, but most of these headings will be important for all projects.<\/p>\n<p>Project root, e.g., <strong>BCCH Radiology (2010)<\/strong><\/p>\n<ul>\n<li style=\"list-style-type: none;\">\n<ul>\n<li><strong>001 Client Data<\/strong> \u2013 any raw data provided by or collected for client: it&#8217;s essential to have an unaltered copy of the original files; altered versions should go in the &#8220;work in progress&#8221; folder. Sensitive client data needs to be encrypted.<\/li>\n<li><strong>002 References<\/strong>\n<ul>\n<li>Journal articles<\/li>\n<li>Data sources not provided by client (downloads from demographic websites, for example.)<\/li>\n<\/ul>\n<\/li>\n<li><strong>003 Work in Progress<\/strong> &#8211; analysis scripts and processed data go here. Remember to have different folders containing all of the analysis scripts and all of the processed\/cleaned data fields generated by your scripts.<\/li>\n<li><strong>004 Project management\/presentations<\/strong>\n<ul>\n<li>The original plan \/ scope document for the project<\/li>\n<li>Minutes\u00a0from weekly internal meetings plus client meetings<\/li>\n<li>Interim presentations and reports<\/li>\n<\/ul>\n<\/li>\n<li><strong>005 Client Deliverables<\/strong> \u2013 exact copy of what was handed over to the client \u2013 nothing else!\n<ul>\n<li>The final report can live here (and not the work in progress folder) from the time you start drafting it.<\/li>\n<li>Also include any manuals, supporting data, and presentations that the client will want to have.<\/li>\n<\/ul>\n<\/li>\n<li><strong>006 COE Deliverables<\/strong>\n<ul>\n<li>Final project report<\/li>\n<li>MITACS report<\/li>\n<li>COE one page summary<\/li>\n<li>COE poster<\/li>\n<li>Final client presentation<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<h1>Document review<\/h1>\n<p><a href=\"https:\/\/blogs.ubc.ca\/coetoolbox\/files\/2018\/03\/document-names.gif\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone wp-image-1656\" src=\"https:\/\/blogs.ubc.ca\/coetoolbox\/files\/2018\/03\/document-names.gif\" alt=\"\" width=\"342\" height=\"456\" \/><\/a><\/p>\n<p>If you email a document for review to all members of your project team, you&#8217;ll get a bunch of versions with different, probably conflicting, edits, and you&#8217;ll have to figure out how to reconcile them all. Instead of circulating documents for review by email, put documents in appropriate shared folders and email reviewers a hyperlink to the document. Everyone can then edit using tracked changes, so that you have discretion about which edits to accept. (See the blog entry about\u00a0<a href=\"https:\/\/blogs.ubc.ca\/coetoolbox\/industry-project-guidelines\/project-documentation\/getting-the-most-out-of-microsoft-word\/\">using Word<\/a> for more about tracked changes.)<\/p>\n<p>If you do end up having to circulate documents via Workspace or email, it&#8217;s your responsibility to keep track of versions of documents, and to apply corrections given on one document to all other documents containing the same content.<\/p>\n<h1>Document naming<\/h1>\n<p>When naming your final documents, keep in mind that the names need to make sense to you, your client, and COE folks current and future. Some of us are going to be reviewing eight final reports and slide decks, and if they\u2019re all named \u201cfinal report\u201d it\u2019s confusing; and\u00a0five years from now someone will need to be able to tell which year&#8217;s &#8220;final report&#8221; this is.\u00a0A format that works is COE + [client name] + [year] + [document type].extension, so \u201cCOE WSBC 2014 final report.docx\u201d or \u201cCOE Boeing 2015 poster.pptx\u201d.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>It\u2019s important that your work be reproducible. The best way of making that happen is to produce scripts that automatically perform all of the steps in your analysis\u2014data cleaning, merging, plotting, statistical analysis\u2026. These scripts won\u2019t be the same as the logs (written or digital) of all of the things you tried along the way; [&hellip;]<\/p>\n","protected":false},"author":22982,"featured_media":0,"parent":601,"menu_order":6,"comment_status":"open","ping_status":"closed","template":"page-templates\/full-width.php","meta":{"footnotes":""},"class_list":["post-610","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/blogs.ubc.ca\/coetoolbox\/wp-json\/wp\/v2\/pages\/610","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blogs.ubc.ca\/coetoolbox\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/blogs.ubc.ca\/coetoolbox\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.ubc.ca\/coetoolbox\/wp-json\/wp\/v2\/users\/22982"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.ubc.ca\/coetoolbox\/wp-json\/wp\/v2\/comments?post=610"}],"version-history":[{"count":20,"href":"https:\/\/blogs.ubc.ca\/coetoolbox\/wp-json\/wp\/v2\/pages\/610\/revisions"}],"predecessor-version":[{"id":1658,"href":"https:\/\/blogs.ubc.ca\/coetoolbox\/wp-json\/wp\/v2\/pages\/610\/revisions\/1658"}],"up":[{"embeddable":true,"href":"https:\/\/blogs.ubc.ca\/coetoolbox\/wp-json\/wp\/v2\/pages\/601"}],"wp:attachment":[{"href":"https:\/\/blogs.ubc.ca\/coetoolbox\/wp-json\/wp\/v2\/media?parent=610"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}