top of page
  • Writer's pictureKelly Adams

How to Document Your Portfolio Projects

Updated: May 14

A person is writing in a small notebook

Recently, someone asked me “is there an ideal format for documentation of projects in a portfolio?” and “what type of information should be included about the project?”. The answer is based on the type of project and where it’s hosted, but here’s a general guideline for you to follow. 

Documentation Recommendations

There are two ways I’d recommend documenting your projects:

  1. Detailed - My recommendation, it’s also a good in case you ever need to review your project in the future.

  2. Minimum - What I consider the bare minimum to do. 

Detailed Write-Up

If you want to be detailed I suggest writing an article like a blog post or LinkedIn article. This helps demonstrates your writing and ability to communicate effectively. Can you explain to a reader your methodology and insights you got?

Here’s what I typically include in a detailed write-up (view those in my Portfolio Projects section in my blog):

This is what I like to have in my detailed article write-up 

  • Introduction: Background, goal, and key questions of the project.

  • Process: Tools used and methodologies applied.

  • Results: Final project images and summary of the data.

  • Insights: Key findings and patterns found.

  • Learnings: New tools or techniques learned during the project.

Simple Summary

But we’re busy and if that’s too much (some of my articles exceed 1000 words), here’s a condensed version in about 5 sentences: 

  1. Background: Project's purpose and goal.

  2. Question: Key objective of the project.

  3. Tools: Main tools used (e.g. SQL, Tableau).

  4. Insights: Major findings and patterns.

  5. Impact: Results and implications of the project.

Here’s an example of my Deep Work Dashboard 2023 article, summarized: 

[Background] This project is an analysis on the time I spent working on difficult tasks like writing blog articles, working on data science projects, or learning more about business. [Question] I wanted to get an overview of how my time is spent and identify patterns in my productivity. [Tools] I used Excel and Google Looker Studio for this project. [Insights] I saw that my average time per week was 18 hours, Wednesday’s were my post productive days and I spent the most time on data science.  [Impact] I realized while I’ve made significant progress in my technical skills, I didn’t spend nearly as much time on learning about business, and that will be my focus this year. Which will only help me be a better analyst. 

Where to Include Your Documentation

Centralized Portfolio

For most projects, whether it’s a Tableau Public dashboard or GitHub repository, having a central location for your portfolio is ideal. It can be a personal website, a one-page site like, or a specific portfolio platform like Maven Analytics Showcase. This way you have a wide variety of projects (e.g. dashboards, code snippets, etc.) listed in one place. I’ve heard recruiters or hiring manager prefer less clicks when trying to navigate to someone's portfolio. So if you have a link to your portfolio on your resume (one click) then they can click a link to your project (two clicks) that should be it. Instead having to navigate to several places to get to your project.

If you are using something like Carrd or Maven Analytics Showcase you can include a brief description on your main portfolio page. Then have links to the project and detailed write-up. This is what I did on my portfolio below.

Spread Out

If your portfolio is currently spread out across a few sites here’s some suggestions based on the site it’s located:

  • Github - Include a readme file with the documentation.

  • Tableau Dashboard - Include the background information either in the description of the dashboard or you can add it directly into your dashboard to make it look like a report. 


Whether you want to write a detailed article or summarize it in a few sentences, the key is clarity and readability. The documentation should showcase your ability to communicate clearly and effectively. Remember, the less navigation required for potential employers, the better. A great suggestion for this is to have a central portfolio and adjust your documentation based on your project. It’s better to have a few short sentences on your project than nothing at all.


bottom of page