Documentation and Reporting

It’s 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—data cleaning, merging, plotting, statistical analysis…. These scripts won’t be the same as the logs (written or digital) of all of the things you tried along the way; they’ll 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.

Reporting Timeframe

You’ll 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.

Working towards these goals, each month you’ll need to deliver sections of your report and documentation. Work with your PA to establish a timeline. It might look like:

  • May 18, 2018:
    • Literature review complete and submitted to your PA. (This date is firm and applies to all teams.)
  • June 8:
    • First draft of introduction and methods section of report
    • Data cleaning complete, including scripts, raw and tidy data, and explanatory documentation
  • June 29:
    • Exploratory analysis complete, including scripts, graphs, and documentation
    • Model-building complete, including documentation
  • August 3:
    • First draft of conclusions section; identify whether materials from previous months should go in the body of the report or in appendices.
    • Scenario-testing complete
  • August 10:
    • Poster and 1-pager draft submitted to PA for review
  • August 17:
    • Poster and 1-pager submitted to client for their approval
    • Full project report draft complete, including executive summary and conclusions
  • August 31:
    • All materials complete; poster and 1-pager approved by client

Project Shared Folder

To make sure that you and the current project team, as well as anyone who is working on the project in the future, know where to find documents, it’s important to have a well-organized shared folder. Don’t store anything on local machines (on your desktop or the C: drive); doing so can present a security risk and slow down your computer.

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.

Project root, e.g., BCCH Radiology (2010)

    • 001 Client Data – any raw data provided by or collected for client: it’s essential to have an unaltered copy of the original files; altered versions should go in the “work in progress” folder. Sensitive client data needs to be encrypted.
    • 002 References
      • Journal articles
      • Data sources not provided by client (downloads from demographic websites, for example.)
    • 003 Work in Progress – 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.
    • 004 Project management/presentations
      • The original plan / scope document for the project
      • Minutes from weekly internal meetings plus client meetings
      • Interim presentations and reports
    • 005 Client Deliverables – exact copy of what was handed over to the client – nothing else!
      • The final report can live here (and not the work in progress folder) from the time you start drafting it.
      • Also include any manuals, supporting data, and presentations that the client will want to have.
    • 006 COE Deliverables
      • Final project report
      • MITACS report
      • COE one page summary
      • COE poster
      • Final client presentation

Document review

If you email a document for review to all members of your project team, you’ll get a bunch of versions with different, probably conflicting, edits, and you’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 using Word for more about tracked changes.)

If you do end up having to circulate documents via Workspace or email, it’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.

Document naming

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’re all named “final report” it’s confusing; and five years from now someone will need to be able to tell which year’s “final report” this is. A format that works is COE + [client name] + [year] + [document type].extension, so “COE WSBC 2014 final report.docx” or “COE Boeing 2015 poster.pptx”.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.