Feedback on project and documentation approach

Hi everyone,

I’m looking for some feedback on the structure and flow of my documentation for this project, Github link below. Please let me know what you think works well, and what you think could be better.

I’m playing around with documenting some of my projects without Jupyter, so in addition I’d be interested to hear from others who have stepped away from Jupyter and what their experiences have been. I do like Jupyter, but I feel it’s worthwhile trying different things as part of my learning process to best appreciate the benefits and limitations of a preferred tool.

Last mission screen

Thanks in advance!


Nice project, well documented, I like the flow, it makes you understand what is going on.

Hi @ajlaan,

To me it looks very professional and yet easy to understand. Though I haven’t learned many points mentioned in your project yet, they are still quite understandable from your easy to read explanation markdowns. Everything looks neat and flows nicely. Great job.

1 Like

Overall, I would say it’s really good work.

Broadly speaking, however, I would recommend the following -

Structure and Flow

Currently, your writeup/documentation is a mix of exploratory and explanatory analysis. Try to keep them separate based on the audience you have in mind.


If you are focusing on expressing your insights or results to someone else, or for others to read, then avoid including any code and/or tables in your writeup. It doesn’t serve much purpose because the ones reading it are trying to quickly see what you have done and what insights you were able to gather. Assume that everyone has very low attention span.


Focus more on visualizations that support any insights you gathered. Lots of information through tables or something like the output of value_counts() are difficult to parse for people who aren’t familiar with the topic or the data. Visually, think where the attention of the reader would go and try to substitute that for a visualization if possible.

Additionally, look into which visualizations you can improve for the reader.

For example,

This is quite good. Now, include those percentage values directly on the visualization itself. On each bar in the bar plot, annotate the percentage. For anyone who looks at the plot will then immediately know what the percentages are without having to trace it on the plot or having to read through your text.

Then in your textual description you can try to narrow it down and focus on the insight itself.

Cleaning up some of the box plots would be good as well. It seems that the outliers are overwhelming the plot itself. IIRC, seaborn’s boxplot has an argument showfliers that you can set to False. Try to see the output based on that, or find other ways to remove or narrow down those outliers.

P.S - Excellent work of creating a function for those visualizations, btw.


Overall, it’s great work. My core suggestions above are around separating the work out into like an exploratory notebook where you focus on the exploration process and questions you ask that lead you to insights, and an explanatory notebook/writeup/blog post which is focused around readers (Technical or non-Technical) to quickly and concisely present your findings.


Thanks for these comments! My original intention, as part of completing the guided project mission, was to produce a single, standalone if you will, document that covers everything. I’m more used to that kind of style from my engineering background, but your input gives me pause to think about how I structure my write-ups with specific audiences in mind.

I’ll work through your suggestions and do a little more general tidying up of the code and graph images (like making them bigger!); this is one I’d like to be able to take a potential employer through since I feel it demonstrates a bunch of relevant analyst skills quite well. For this, I think a write-up/blog post that concisely presents the findings, and a notebook explaining the exploratory data analysis process would suit my needs - do you agree?

1 Like