Serendeepia Playbook

Documentation

We use online tools to store all the documentation. The documents for the projects are in a shared folder in Google Drive. This is the root structure we follow:

/ (root dir) The root contains general documents.
/Projects/ Contains one directory per project.
/Projects/2018-01-02-XXX/ Example of a directory for a project. These directories must be named with the date first so they are easier to sort this way.

We have have one shared folder for clients that follows the same structure as the projects. This shared folder for clients contains only legal documents and the offer and budget documents of the projects. These documents are not related with the development of the project.

Structure of a project

This is the structure per project:

(project root dir) Contains working documents we will never send to the client.
Deliverable/ All the deliverable documents we have submitted to the client.
Deliverable/2018-01-02-OFFER-v1 Example of deliverable documents. It must start with the date we submitted it to the client and end with the version. We cannot modify this documents, they must be in read-only mode.
Working/ All the deliverable documents that are under development.
Working/OFFER-v2 Example of a deliverable document under development. This documents only have the name and the version.

The documents must have the versioning activated and we should name the versions with two numbers. The first one implies big changes and the second implies additions. Typos and bugs do not modify the version number, unlikely in semantic versioning.

One person is in charge of each document.

Code organization

NOTE: the structure might be different for public projects as needed

</tr> </table> Note that the code is evolving continuously and old experiments might not work with recent code. In order to replicate the experiments we should use the commit more close to the date the experiment was launch. We try not to perform big modifications in the code under `src/` but a continuous addition of new features.
/ (root dir)
/README.md Description of the project and main guideline to execute the commands.
/LICENSE License of the code
/src/ Source code of the project. It must contain at least one main module name.
/src/requirements.txt File with the dependencies of the project
/data/ Contains the data of the project or a description of how to get it.
/data/README.md Description of the data: how is the data, how we clean it, where is the data (aws, gs,...), etc
/data/raw/ Contains raw data
/data/clean/ Contains the data cleaned
/papers/ Directory with the papers
/papers/README.md Description of the papers. It contains a table with the title of the paper, the date it was published, a link to the paper inside the repo, a comment describing why this paper is relevant for the project and a ranking of how relevant is the paper (1 less relevant, 2 medium relevant, 3 very relevant). Most relevant papers must be on top of the table.
/papers/2016-TITLE.pdf</td> Example of paper in the repo. The names must start with the date they were published followed by the title of the paper.
/experiments/ Directory with the experiments
/experiments/README.md Brief description of the experiments. Most recent experiments must be at the top.
/experiments/2017-01-01-DESCR/ Example of directory for an experiment. It must start with the date the experiment started. It also contains a README.md file with the description of the experiment and its results and any script used.
/exploratory-analysis/ Directory with all the code used for the exploratory analysis. This is used mostly as a backup of the exploratory analysis, so there are no rules for its internal structure.
/documentation/ Directory with all the documentation required for the dissemination and exploitation. Every piece of code, definition, image or video relevant to the project which can be further useful for writing a paper/patent/talk, should be stored here.