diff --git a/docs/_toc.yml b/docs/_toc.yml index 0f25a75..7851264 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -14,6 +14,7 @@ parts: - file: docs/folders-and-naming - file: docs/git-workflows - file: docs/notebooks-workflows + - file: docs/presenting-results - caption: Gallery chapters: - file: docs/gallery diff --git a/docs/notebooks-workflows.md b/docs/notebooks-workflows.md index 59e995c..7760f44 100644 --- a/docs/notebooks-workflows.md +++ b/docs/notebooks-workflows.md @@ -1,6 +1,15 @@ -# Guidelines for Documenting and Styling Analytical Notebooks -This section provides best practices for structuring analytical notebooks to enhance readability. The guidelines include recommendations for hiding code cells to maintain a clean appearance in Jupyter Book, incorporating references where relevant, and organizing content logically to ensure clarity for readers. +# Documenting and Styling Analytical Notebooks +This section provides guidelines for structuring analytical notebooks to enhance readability. The guidelines include recommendations for hiding code cells to maintain a clean appearance in Jupyter Book, incorporating references where relevant, and organizing content logically to ensure clarity for readers. -- **Structure**. In all the Data Lab projects, please follow [this analytics structure](https://github.com/worldbank/sudan-poverty-monitoring/blob/main/docs/2-analytics.md). -- **Editing _toc.yml** -- **Removing/hiding cell blocks** All notebooks will be rendered in Jupyter Book. To enhance readability, ensure code cells are hidden or removed using cell tags. In some cases, you may use the hide-input cell tag. \ No newline at end of file +## General Notes +- **Notebook subfolder**. +As noted in the [Naming and Folder Setup section](/docs/folders-and-naming.md), ensure you create a subfolder within the project’s notebooks folder. This subfolder should be named based on the theme of your assignment, serving as a dedicated space for your notebooks. This practice is especially important, as most Data Lab projects cover multiple topics and involve collaboration among several team members. +- **Notebook Structure**. In all Data Lab projects, we adhere to [this analytics structure](https://github.com/worldbank/sudan-poverty-monitoring/blob/main/docs/2-analytics.md). Ensure that your notebook follows this same structure. + +- **Adding a README.md** If you look at the recommended notebok structure, it has sections on data used and methodology. In some cases, this information may better presented in a separate markdown file. You can add a ```README.md``` within your notebooks subfolder. This will provide detailed information about data sources and methodology. +- **Previewing Jupyter Book** As you are aware, the ```_toc.yml``` controls whats rendered in the Jupyter Book. Please edit the file accordinly to add your notebooks and other ```markdown``` files as needed. This will allow you to build the book locally using ```make build``` command and preview and check if your notebooks are rendering as expected. +- **Removing/hiding cell blocks** All notebooks will be rendered in Jupyter Book. To enhance readability, ensure code cells are hidden or removed using cell tags. In some cases, you may use the hide-input cell tag. + + +## Other Things to Note +- **Headings**. Jupyter books renders all top level headings as sections in the Table of contents, so make sure to only use ```#``` for the top heading of your notebook. diff --git a/docs/presenting-results.md b/docs/presenting-results.md new file mode 100644 index 0000000..9ae9583 --- /dev/null +++ b/docs/presenting-results.md @@ -0,0 +1,11 @@ +# Presenting and Communicating Data Outputs +This section provides guidance on effectively preparing and sharing data results with clients, many of whom may not have a background on the data, variables and methods you have used in the analysis. The aim is to help team members present insights in a clear, accessible, and impactful way, ensuring that complex findings are communicated without unnecessary technical jargon. + +## Notebook Content Guidelines +In the [notebook guidelines](/docs/notebooks-workflows.md), we mentioned that we adhere to a structure which provides details about the dataset being used and other methodological details. However, in each section of the analysis, also ensure that you clearly define which variables are being used from the data, whats the unit of analysis and so on. + +## Explanations for Visuals and Tables +In the notebook, add brief narratives or observations for each table and figure. When presenting, be sure to explain key insights, trends, or notable absences in the figures and tables. + +## Preparing for and Addressing Questions +Most of our clients are World Bank Task Team Leaders (TTLs) who are typically economists with Master’s or PhD-level expertise. While they may not be familiar with every dataset or method you’ve used, they are well-versed in rigorous statistical analysis and expect us to apply statistically sound methodologies. It’s essential, therefore, to keep this in mind and anticipate the kinds of questions they may ask.