unicef/magicbox

A platform that uses real-time data to inform life-saving humanitarian responses to emergency situations

MagicBox

This repository is no longer actively maintained.

A platform that uses real-time data to inform life-saving humanitarian responses to emergency situations

About

MagicBox is an open-source platform that uses real-time information to inform life-saving humanitarian responses to emergency situations. It's composed of multiple GitHub repositories designed to ingest, aggregate, and serve data.

You can read more about the project's purpose on unicef.org.

What's here

This repo is the "parent" repo for all MagicBox-related projects. It hosts the documentation and other misc. resources for MagicBox. Code for other projects, like the API and front-end, are hosted in other repositories. See the project index for a full list of MagicBox-related repos and their respective maintainers.

Contributing

We are looking for collaboration from the Open Source community! There's so much we want to do, including but not limited to: enhancing existing applications with new features, optimizing the technical tools and algorithms involved to accommodate data challenges, and bringing our work closer to the public to leverage their inputs via blog posts and tutorials.

• Please read our contribution guidelines for details on what and how you can contribute.
• Check out our Development Project Board.
• Look for tasks labelled good first issue under the Issues tab in each repo.
• Join our Gitter channel.

Documentation

Project documentation is hosted on ReadTheDocs. Its current version is mostly suited for developers who want to understand more about our underlying tech. We are hoping to establish a more user-friendly version soon, one that is readable by our potential users (e.g. data scientists and decision-makers in UNICEF country offices, state governments, other UN agencies).

Resources

To understand MagicBox better:

• Read the README for each repo (full list is here). An architecture diagram of how these components are connected to one another is coming soon.
• Check out our Medium blog posts.

magicbox's Issues

Write an article about MagicBox for Opensource.com

Summary

Help get exposure about MagicBox by writing an introduction to the project and its purpose for Opensource.com

Background

Once MagicBox and related projects are better ready to handle new contributors, we can think about exposure and visibility for MagicBox. Once we are confident about the contributor experience for MagicBox, we should try to take an active approach to promoting the projects and gain community interest (and maybe, a few new contributors too)!

Opensource.com is a journalism site sponsored by Red Hat that promotes open source news, guides, tutorials, and more. An introduction to MagicBox is a great fit for the site's audience. We also benefit from the size of their audience too (2017 brought in over 13 million page views to the site).

Details

Once we are better prepared to handle new contributors and I have more experience with the project, I plan to write an introductory article to help tell the story of MagicBox and share it with Opensource.com.

When this moves off the backlog, we can revisit for specifics.

Action

Write an article that introduces the basics of MagicBox, explains its purpose and the background behind why UNICEF is developing this project, point out how to get involved

[Post-RH] Update GitHub development project board

The MagicBox - Development project board needs to be updated and triaged now that the Red Hat engagement ended.

What to do

To close this issue, the following should be done:

• Issues / cards under "In progress" and "To do" should be correct (are we doing the things listed there right now or are they backlogged?)
• Convert any notes under "To do" or "In progress" to full GitHub issues
• Add new comments / updates to GitHub issues under "To do" or "In progress"
• File new issues to add to the board (for things that need to happen but are not yet on the board)

Why do it

1. Makes it clear what we're working on now and where the team's development focus is going (guiding others to where to spend their time and be most helpful to MagicBox)
2. Notes do not track conversation and cannot be assigned; they are good for short notes but bad for real features or bugs. Note cards should only be under "backlog" for half-finished ideas; everything under "To do" and "In progress" should be real GitHub issues to track discussion and assign them
3. Shares info on where an important task is; getting some of our discussion out of video calls and into the public
4. Make sure we're tracking important features, bugs, or tasks in a GitHub repo; fills missing gaps in knowledge from development team to community

Aggregate polygons of one shapefile by another

Problem description

When working with region-based datasets, we usually encounter the situation where the polygons in one dataset do not geospatially align with the polygons in another.

Examples:

• Cell tower's coverage areas VS. administrative divisions
• Voronoi diagram of Ebola outbreak points VS. administrative divisions
• Health zones VS. population administrative divisions

One feature we want for the MagicBox Platform is the ability to aggregate the values for polygons of one shapefile/GeoJSON/csv based on the polygons of another shapefile/GeoJSON/csv. Hence, corresponding with the examples above:

• Cell tower's coverage areas determine where cellphone calls originate. To know mobility i.e. how people move from one place to another, we need to know where people are at a given time and the call locations will tell us that. But we are not interested in the human movement from one coverage area to another; rather, we want human movement from one administrative division ("admin" for short) to another. To generate this "mobility by admin" data, we have to aggregate the mobility values from the "coverage area" shapefile/GeoJSON/csv to the "admins" shapefile/GeoJSON/csv. The output will be a new column in the "admins" file: the mobility_value column. Summarized problem statement: Aggregate mobility values by admins, based on mobility values by cell tower's coverage areas.
• From the Ebola outbreak points, we can generate a Voronoi diagram showing the probability of new contract cases. These Voronoi polygons of course won't fall squarely on the admins polygons. What we want, then, is to assign the new_case_probability value to the admins, so that we know which admins are more vulnerable than others and thus need more attention and resources from the government/aid agencies. Summarized problem statement: Aggregate new case probabilities by admins, based on Voronoi diagram of Ebola outbreak points.
• We have the number of Zika cases per health zone, but those values will be more helpful to MagicBox data scientists if they are by population area. An derived use case is to connect this case-per-admin data with the mobility-per-admin data above and plot the (potential) spread of disease. Alternatively, we might have data on the medical capacity per health zone (e.g. the number of doctors/nurses/community health workers/vaccines). If we can aggregate these values by population admin, governments and policy-makers will be informed of how well or uderrserved each admin is. Summarized problem statement: Aggregate [a numeric attribute] by admins, based on [that attribute's values] by health zones.

The pattern is spotted:

• Input: geofile_1, geofile_2, an attribute_of_interest that exists in geofile_1
• Output: geofile_2 augmented with attribute_of_interest

An example use case

Here you see a Voronoi diagram over a country shapefile. The generating points are arbitrary, but we can assume they are cell tower locations (pairs of coordinates to be exact).

This Medium article discusses in-depth this use case, though it goes one step further with the output. Going beyond (origin_admin, destination_admin, mobility_value) for each row/tuple in the resulting geofile, it asks for a mobility matrix. The latter is easily generated from the former, though.

Write a docs section on setting up a testing framework for MagicBox repos

Summary

Research on testing framework options for MagicBox repos and finish writing the Set up a testing framework section in the GitHub Workflow docs.

Details

PR #39 has completed the sections on continuous integration and code health checks. However, a need emerged as I wrote about setting up CodeClimate. That is, CodeClimate can read and display results from test coverage reports, but it does not run these reports by itself. Therefore, a test coverage tool needs to be set up. As I came to learn this, I also found out that MagicBox repos do not have a uniform test pattern / testing framework yet. This should be addressed among our dev's.

Identify 3-5 "starter" tasks or bugs in any MagicBox project

Come up with 3-5 bugs or simpler tasks to work on across any MagicBox project; clearly label them as "good first issues" and leave them open for new contributors to try working on

How to do it

1. Across core projects, come up with short list of small / quick improvements or fixes wanted, but not urgently needed
2. File new issues / update existing ones to explain easier tasks
   • Explain the problem, clearly explain the deliverable / desired result
3. Label these tasks clearly with a "good first issue" label
4. Keep them open for new contributors or team members to work on (core / active contributors shouldn't take these tasks)

Why do it

When people come wanting to contribute, we need to help guide their first steps. Simple or "easyfix" tasks are great ways to introduce a new contributor to your project by giving them a small, manageable area to focus on or work. This supports a marginal improvement to your project, but also delivers purpose to someone navigating your code for the first time. These tasks get them more comfortable with the project and could edge someone towards contributing bigger things. But it's easier to start with a smaller piece first.

Create production/staging/dev deployment slots for Mobility Mapping

Create new repo to be a git submodule for other repos

Summary

Create a new repo in UNICEF to hold common documents (e.g. Code of Conduct, issue / PR / README templates, contributing guidelines, etc.) to be used as a git submodule in other GitHub repos

Background

Every GitHub repo can contain a special .github folder that holds "special" files, like what's shown in the community report card. Some of these files may be the same across multiple UNICEF or MagicBox repos. If a decision is ever made to change a file used across many repositories, that means every repository has to be manually updated…

A simple "hack" is using a git submodule that anyone can clone to the .github directory in their repo. This clones a git repo inside of a git repo. So, if any changes are made to a global file, a project maintainer only has to update the git submodule instead of manually updating the files in each repo.

Details

I haven't tried this out, but in theory, it should work.

If the solution makes sense, we need to create a new repo underneath the UNICEF organization to hold these common files. Possible name ideas could be community or magicbox-community. This also provides us a way to make unique discussions to the MagicBox community as issues.

Alternatively, instead of a new repo, this repository (i.e. UNICEF/magicbox) could serve this purpose. However, the use of this repo, other than the wiki, is not yet clear to me. (Thus, I tagged this issue with needs feedback).

Outcome

Important documents (e.g. code of conduct, misc. templates) shared across multiple UNICEF / MagicBox repos become easy to maintain and it's less work for a small team to remember to update everything if a change is agreed on

Write a general, 2-3 paragraph "mission statement" for MagicBox development

Write a short mission statement that explains the general purpose of MagicBox, what it aims to do and accomplish, and what challenges it solves. Should be 3-4 sentences and included in the contribution guidelines

How to do it

1. Get clear answers to these questions:
   • What does MagicBox do?
   • Who is it designed for?
   • What challenges and problems does it solve, generally?
2. Write two to three paragraphs to answer these questions, as if you were writing to someone who had never heard of MagicBox before
3. Review paragraphs with other team members, get feedback
4. After feedback / revisions, add the mission statement near the top of the contribution guidelines

Why do it

MagicBox is an awesome project because it solves unique and compelling problems and challenges faced by UNICEF Innovation. A mission statement helps capture that vision and better communicate our challenges with outsiders to the project. This helps an outsider understand our goals, what the project is designed for, and who it is designed for. From there, an outsider is better informed and (hopefully) motivated to get involved and contribute with the project, if they are interested.

A mission statement is a key part to how we communicate our big-picture vision. UNICEF is an organization with many focuses and goals. This is how we bring the areas we focus and work on "down to earth" for people who may not know much or any of those focuses or goals. It's a part of how we present our project to the public (think marketing).

Set description, URL, topic tags for all MagicBox repos

Summary

Set a simple description string, create topic tags, and add URL if necessary for all MagicBox repos

Background

All GitHub projects can set a description string that appears in global search and quickly summarizes the repo's purpose. A URL can also be set for extra reading or for a demo. Topic tags are a newer addition to help make projects easier to discover by major keywords.

Details

Description strings should be set by default for every MagicBox-related project. The same description detailed in #2 can be used.

If a repo has a live demo or an external resource for someone to read or try out the project, that should be set.

Topic tags are important and can also help organize projects internally and raise visibility outside of UNICEF. Some suggested topic tags:

• magicbox
• javascript
• python
• react
• Any frameworks or specific technologies used make good topic tags for discoverability

Outcome

Projects are easier to find and understand at a glance, and are more inviting to someone who may discover a MagicBox project

Write common README template for all MagicBox repos

Summary

Write a basic template for a README to be used by other MagicBox projects (possibly other UNICEF projects)

Background

A README is the front door to an open source project. It's the first impression a project makes on anyone, whether it's a potential user, contributor, or supporter. A good README should…

• Clearly and simply explain what the project is
• Explain how to use the project (if necessary), or point to full documentation on how to use
• Explain how to contribute (or point to full contributing guidelines)
• Mention any legal notices (e.g. what license the project uses)

Check out the maturity model for READMEs. Let's try to get some Level 4 READMEs! 😄

Details

Every README for each project will be different. This issue is not about writing specific READMEs, but writing a good base template that other repos or UNICEF staff members can use to write good READMEs.

Ideally, the deliverable product is a template that has some "fill-in-the-blank" things, but more questions to prompt a maintainer to answer when putting together their README. To do this successfully, I want to do more research on how we can encourage others to write Level 4 (or better) READMEs without writing it for them, as explained in the maturity model.

Outcome

General template for MagicBox / UNICEF projects to use for writing a README for their open source project, to help invite new contributors and make the "first impression" a good one

Identify populations X kilometers from nearest health facility

We need to help a government identify the populations most in need of infrastructure and planning for ebola response.

Given the following data sets:

• a list of population points (50k points)
• a list of health facilities (1.4k points)
• shapefile for DRC at admin level 2,
• roads shapefile for DRC

...create a Jupyter notebook that serves all population points x kilometers from nearest health facility.

The final project should be an open-source, standalone GitHub repository, with a README and at least some test coverage. The readme should address (1) what this repo is or does, and (2) how to install and use it.

Identify user needs for improved user documentation

Better user documentation is important for people who will use MagicBox; to write effective user documentation, create a list of primary users of MagicBox and identify and prioritize new documentation

How to do it

1. Identify / create list of primary users of MagicBox
   • Who uses MagicBox… who cares, who wants to use it?
   • Country offices? State governments? Other UN agencies? External stakeholders?
2. Put yourself in their shoes and write list of things a type of user will want to know
   • What do they need to know? What do they want to know?
3. Write new documentation for users of MagicBox that explains how to use and understand output

Why do it

Users are important to MagicBox. Our users shape the development direction of the project and what data or analysis is needed most urgently. Creating better user documentation not only helps end users of MagicBox, but it also lowers the "minimum activation energy" for a new contributor in an open source community. If developers understand the users and their needs, there is less wasted time during the development cycle and better focus on meeting user needs.

Document all UNICEF repositories related to MagicBox

Summary

Create a documented list of all repositories in UNICEF GitHub organization related to MagicBox to better connect related projects together

Background

There are several repositories related to MagicBox across the UNICEF GitHub organization. There are four I am aware of:

1. unicef/magicbox
2. unicef/magicbox-open-api
3. unicef/aggregate_airport_mobility
4. unicef/assign_admins_to_airports
5. unicef/coordinates_to_admin_id_server

Some are linked in the MagicBox wiki, some are not. Not all of them are clearly explained in how they relate to MagicBox.

Details

The deliverable can be a new wiki or documentation page. It can be a simple list or a table, so it is easy to maintain and for an active contributor to know if it is outdated. Each repo should have a 1-2 sentence description of its purpose or function (longer descriptions belong in the repo's README).

This provides a jumping-off point for a new contributor or interested person to explore the related projects without manually searching for them in the UNICEF GitHub organization.

Action

Create a new wiki or documentation page with a simple list or table linking to every repo related to the MagicBox project to help document the relationship between different repos and MagicBox

Write a MagicBox user persona and tie it to mission statement (blocked by #32)

After writing a mission statement (see #32), write one user persona for MagicBox and tie that persona to our mission statement; publish the persona to our ReadTheDocs documentation

How to do it

1. Go back to list of users from #32: of those users, choose one whose use case is important and helpful to highlight to a new contributor / team member
2. Write a persona about one of these users: What do they need from MagicBox? How do they use MagicBox?
3. Review persona with other team members, get feedback
4. After feedback / revisions, add as new personas page to ReadTheDocs documentation

Why do it

A persona helps us keep who our users and their needs in mind when developing. A persona is also a story: it's an opportunity to show an outsider how this project actually meets the goals and purpose it meets from our mission statement (#32). This does two things:

• Appeals to the unique nature of our project and demonstrate value in contributing
• Helps a new contributor understand our project and user needs better

Writing a persona for an important user of MagicBox introduces the project for us automatically through documentation.

Write high-level introduction to MagicBox and how it's built

Summary

Write one or two page doc to explain MagicBox projects, their relationships, and how it all fits together (complements #15)

Background

There's a lot of repos and they're listed in the project index, but that page isn't helpful. It gives us a bunch of "dots" but not how they're connected. It's confusing for a newcomer to understand how the projects fit together, what each one does, and why they are important.

Details

A one or two page document to explain that pipeline, or flow, of how the repos are connected and how the data is processed will be helpful. I am writing a short document to give that explanation / introduction. The purpose is that we could share this with anyone and they could get a brief understanding of the project and how it fits together.

I plan to use past Medium articles and some of the info on the unicefstories.org site to create this.

Outcome

Easier to understand the project, relationship among repos is more clear, easier to introduce someone to the projects

Establish public communication channel for MagicBox projects

Summary

Create public communication channel for open source community to engage, interact, get help, get involved with MagicBox projects

Background

Open source projects usually have a place where interested users, developers, or contributors can ask questions, get help, talk about the project, and more. Having a public platform to do this is important for the health of a project. Otherwise, it's like having a public train system, but to get to it, you have to go through membership-only gym.

A public channel truly enables us to engage with the community because it enables two-way interaction between the community and the Office of Innovation.

Details

There are many platforms that exist, but I suggest these three, ordered in rank by most preferred to least.

1. Internet Relay Chat (IRC) (also supports Riot)
2. Gitter
3. Slack

IRC

IRC is most preferred because it brings us directly into an inter-connected "bubble" of other open source projects and communities. Countless projects use the freenode IRC network, and many communities are based there for over two decades. Using IRC also taps us into that network.

GItter

Gitter is also a popular option, but I believe it to be slightly less connected as compared to IRC. I've also found its mobile support to be lacking.

Slack

Slack is a well-known platform, but it is proprietary and also may require a paid plan in the future. However, it does offer granular permissions and easier separation of public vs. private channels (the other platforms support public vs. private too, but it's not as straightforward).

Outcome

UNICEF Office of Innovation and MagicBox projects are better connected to the wider open source community, and new users or contributors are better able to get involved with projects

Connect gadm3-6 topojson files to databricks

Create production/staging/dev deployment slots for Magicbox API

Create issue / pull request templates for core MagicBox projects

Summary

Create a common set of issue / pull request templates that simplify reviewing new contributions and bug requests to core MagicBox projects

Background

Issue and pull request templates are a GitHub feature that let a project maintainer create a template that anyone filing an issue or creating a pull request sees. These are helpful to guide new contributors to leave more helpful bug reports / feature requests, getting valuable information for diagnosing problems, and to guide new contributors (e.g. providing a "checklist" of things to review before submitting).

Core MagicBox projects are:

• unicef/magicbox-open-api
• unicef/magicbox-maps

Details

The easiest option is to use a single issue / pull request template across all MagicBox-related repos. This simplifies adoption and ensures consistency for the contributor experience. However, this may not be possible.

Before creating a template, each project (or all projects) need to identify…

• Minimum required information for bug reports
  • What info is helpful to diagnose a problem
  • Version numbers? Logs?
• Helpful pointers for others making feature requests
  • What questions do we want to ask? Why does someone need a feature?
• Checklist of routine tasks every pull request should follow
  • Before someone commits code to the repo, what should they check for?
  • Are there guidelines for style they should follow? Should they run any tests before submitting a pull request?

This list may vary by project. Whether all MagicBox projects use the same templates or not depends on unique needs for each project. Alternatively, a "base" could be drafted, and then each project can tack specific requirements on at the end.

Action

Create issue / pull request templates for core MagicBox repos to help…

1. New contributors make a first contribution
2. Maintainers review contributions as the project scales up

Make "share" and "save config" buttons configurable

Make "share" and "save config" buttons configurable in ./client/config.js

Share public version of MagicBox diagram on ReadTheDocs

@mikefab has a full diagram of how the pieces of MagicBox fit together and what the components of the project are; we need to make a public version of that document and add it to our documentation

What to do

1. Create a public version of the graph with sensitive information or resources removed
2. Submit a pull request to unicef/magicbox with the picture (maybe to the index page underneath the table of contents section for now?)
3. Show diagram in the MagicBox README

Why do it

MagicBox is a complex project with many pieces. We want contributors to spend time working on valuable areas of MagicBox that help the project. By investing time and effort in the project, we want to reward that time and effort with accepted contributions. To accept meaningful contributions, we need to make it more clear how MagicBox fits together and what the "core" components are.

Write section on best practices for reviewing a PR in GitHub Workflow doc

Summary

Finish writing the section Reviewing pull requests in Github Workflow doc

Background

@thoat and I had a conversation today about this section in the docs and what I meant with some of my notes – from the explanation, it would be more or less easy to update the documentation to be complete and make sense.

Details

It's mostly expanding on the existing notes on following best practices when reviewing a pull request and how to be effective with reviewing them.

I assigned this to me because this one is easier and still fresh in mind. I think I'll be able to do this in a week or less. 🙂

Outcome

Easier to understand best practices for reviewing new pull requests and what steps to follow when someone makes a new pull request

Kepler.gl mobility viz 1: Create a deck.gl visualization

This issue is really and epic story. It involves ingesting, querying, and displaying mobility. We have two types of mobility:

• point
• polygon

and two types of temporal ranges

• historic (actual dates)
• baseline (an aggregation of multiple days)

Sample data

• baseline polygon
• Single day tower to tower mobility generated using weather towers in Brazil and gravity model.

Loading sample [baseline mobility data] map, a user should be able to click on a particular administrative region and see egress from that region to the surrounding regions, and easily determine the locations where more or less individuals are traveling.

Two ways to represent mobility are arrows (width based on amount of travelers) and opacity.

Examples

• repo webgl
• repo mapbox.gl

Import mobility through Superset into olap db like druid

Superset & Druid docs
Sample dataset (clicking will download a csv file directly)

Map relationships between apps, repos, and azure resources.

Set up GitHub project boards for MagicBox

Summary

Set up and configure GitHub project boards for MagicBox contributors, to help track progress of work in a kanban-style workflow

Background

GitHub project boards are a kanban-style tool built into all GitHub repositories. Think of it as a Trello replacement that also integrates with GitHub issues and pull requests. This helps clearly document progress on a set of issues and also identify who is working on a task (using issue / PR metadata).

Additionally, project boards come with the added benefit of being publicly viewable, making it easy for anyone to follow along with project status and timeline.

Details

Project boards need to be set up in an easy-to-understand way, so all MagicBox team members understand how to use them effectively, without becoming a burden. Simple automation makes it easier to maintain project boards.

Earlier today, we tried organization project boards (i.e. sharing issues / PRs across multiple repos in a single board), but the project boards seem to private only to organization members. I reached out to GitHub to ask if there is a way to make organization project boards publicly viewable. I believe the transparency that comes with publicly viewable project boards is important.

I am using a project board for community management in this repo, but this could be moved or migrated elsewhere once we determine whether organization boards are a viable option.

Outcome

Project boards that clearly document on-going work, shows available capacity of current team members, and helps eliminate bottlenecks; makes it easier for new contributors to see what tasks are already in progress, need help, or are not being worked on

Given a csv of geospatial points and a shapefile, create a clipped voronoi tessellation

A clipped Voronoi diagram is one that is confined to a compact domain (i.e. a bounded and closed 2D region or a 3D volume). In the example above, a normally generated Voronoi diagram will have some cells infinite or partially outside of the country boundary. However, only the cells that lie within the country boundary are of our interests.

Admin 1 geojson: http://myjson.com/wvt2s

The output of this task could be used as input to #44.

Set up automatic CI testing for new pull requests

Summary

Set up continuous integration (CI) to build new pull requests against MagicBox projects

Background

CI is important for a project because it prevents simple mistakes or oversights making it into a production code base. Effective test cases can be written to hook into any of the CI platforms available, such as TravisCI, CircleCI, and others.

CI is helpful for advanced contributors (especially in a small project) because of limited development time and the ease of making mistakes. It happens. It's a safeguard to help prevent mistakes from entering "production" code.

CI is helpful for new contributors because it provides instant feedback if a pull request breaks the project or not. A contributor can see feedback and a stacktrace of what went wrong so they can fix their issue or ask for specific help if needed (instead of waiting for a maintainer to review the PR and give that feedback).

Details

There are general test cases available for many programming languages. Those could be set up easily. More advanced CI would encourage contributors to write test cases into the code, and then CI platforms could execute those test cases.

Each MagicBox project will likely needs its own unique CI configuration. If developer bandwidth is low, some projects that are more "publicly visible" should be prioritized for CI coverage.

Outcome

Pull requests to a MagicBox project are tested and verified to build successfully before a maintainer reviews a new contribution; this helps prevent bad code making it into the code base and provides immediate feedback to new contributors to fix oversights or mistakes

Connect healthsites from healthsites.io

Deploy magicbox-kepler-demo to Azure

Create a matrix of repositories and which ones have: Travis CI, Sphinx, and ReadTheDocs set up.

test

test

Adopt code of conduct for MagicBox projects

Summary

Adopt code of conduct (Contributor Covenant?) to set clear expectations for acceptable and unacceptable behavior in MagicBox projects

Background

Having a code of conduct for an open source project is important. A company or organization has a human resources department and expectations for how employees are to behave, but an open source project does not. Setting clear expectations for what behavior is appropriate or not is important, and also assures confidence in contributors that their experience will be positive.

See GitHub's open source guide for a more in-depth explanation of the value of a code of conduct.

Details

Writing a code of conduct is hard to do the right way. I am a fan of the Contributor Covenant, which does the work of writing it and helping us set clear expectations. I think it will be easy to implement and use this CoC for MagicBox projects.

Extra consideration is needed about where code of conduct violation reports should go (to what email address), and also how violations will be handled. It's impossible to map out every scenario, but if someone does report a violation of the CoC, it should be handled respectfully and promptly. Setting a CoC without having a plan for how to actually enforce it is not a good idea.

Action

Agree or write a code of conduct to set clear expectations and guidelines for contributor behavior in MagicBox projects, have a general idea of how to handle violation reports should they ever happen

Connect OSM schools

Choose documentation platform

Summary

Establish a documentation platform for hosted documentation about MagicBox projects

Background

Effective documentation is critical in technical projects – open source or otherwise. However, it's especially helpful for MagicBox because of the small team size and need to engage with the open source community.

Better documentation for MagicBox means…

1. New contributors / contractors learn the pipeline / software quicker
2. Design decisions are better documented (less time back-tracking)
3. Enables other contributor-oriented documentation (e.g. issue / PR templates, see #3)
4. Easier to tell a story (e.g. Opensource.com, see #8)

So far, a lot of highly technical information is shared through Medium blog posts, which is helpful, but blogging isn't effective as a long-term strategy for referencing technical information for MagicBox. This type of information should live in documentation, while stories behind how it happens is better suited for blog posts.

Details

Choosing a platform should be based on what is most intuitive and easiest to maintain for the team. A popular platform is ReadTheDocs, which uses a Python-based toolchain. Thus, it also makes it an especially fantastic tool for Python projects, but it is still great for any programming language regardless.

I want to do additional research to see if there is a Node / JavaScript-tailored docs platform, since many of our projects are in Node. However, I think ReadTheDocs may still be the best solution for this.

Outcome

Better documentation means a better experience for people to contribute to our projects; enables us to bring new people into the community easier and also provide reference points for various design decisions in the future (i.e. why we did something the way we did)