diff --git a/docs/contribute.md b/docs/contribute.md index cf60574..c696e22 100644 --- a/docs/contribute.md +++ b/docs/contribute.md @@ -5,9 +5,9 @@ Developer Guide This document contains additional information on contributing to dribdat as a developer. If you are just interested in connecting to dribdat's API, scroll down to the [API overview](#api-guide) For more background references, see the [README](https://github.com/dribdat/dribdat#dribdat). -# Software Architecture +# Welcome, contributor! -This code is originally based on [cookiecutter-flask](https://github.com/cookiecutter-flask/cookiecutter-flask), which has a number of helpful [developer features](https://github.com/cookiecutter-flask/cookiecutter-flask#features). It is a Python 3 project that uses the Flask microframework and SQLAlchemy for data modelling on the backend. A plain JSON API, along with Jinja templates and WTForms, serves data to a frontend based on Bootstrap 3 and jQuery. +Thanks for checking out `dribdat` - made for brilliant people like you. This code is originally based on [cookiecutter-flask](https://github.com/cookiecutter-flask/cookiecutter-flask), which has a number of helpful [developer features](https://github.com/cookiecutter-flask/cookiecutter-flask#features). It is a Python 3 project that uses the Flask microframework and SQLAlchemy for data modelling on the backend. A plain JSON API, along with Jinja templates and WTForms, serves data to a frontend based on Bootstrap 3 and jQuery. ![Sketch of project architecture](images/architecture-dribdat.svg.png) @@ -15,7 +15,12 @@ This code is originally based on [cookiecutter-flask](https://github.com/cookiec It is possible to start a development build using the `docker-compose.local.yml` configuration for Docker Compose. Otherwise, you need to set up your coding environment as follows. -(1) Install [Python](https://python.org) and [Poetry](https://python-poetry.org/) to start working with the code. Virtualenv and `pip` are also supported as alternatives to Poetry. +(1) Install [Git](https://git-scm.com/), [Python](https://python.org) and [Poetry](https://python-poetry.org/) to start working with the code. Virtualenv and `pip` are also supported as alternatives to Poetry. Then get the sources using `git`: + +``` +git clone https://codeberg.org/dribdat/dribdat.git +cd dribdat +``` (2) You may need to install additional system libraries (`libffi`) for the [misaka](http://misaka.61924.nl/) package, which depends on [CFFI](https://cffi.readthedocs.io/en/latest/installation.html#platform-specific-instructions). You are likely to also need development headers for Python. @@ -25,15 +30,11 @@ It is possible to start a development build using the `docker-compose.local.yml` (3) Next, run the following commands from the repository root folder to bootstrap your environment with Poetry: ``` -poetry shell poetry install +poetry shell ``` -Or using plain pip: - -``` -pip install -r requirements/dev.txt -``` +(If using plain pip: `pip install -r requirements/dev.txt`) (4) By default in a dev environment, a SQLite database will be created in the root folder (`dev.db`). You can also install and configure your choice of DBMS [supported by SQLAlchemy](http://docs.sqlalchemy.org/en/rel_1_1/dialects/index.html). In production, the `DATABASE_URL` configures connectivity to an SQLAlchemy-compatible database engine. This requires a `DRIBDAT_ENV=prod` configuration. diff --git a/docs/images/screenshot_project_new.png b/docs/images/screenshot_project_new.png index e2978fc..3b29de4 100644 Binary files a/docs/images/screenshot_project_new.png and b/docs/images/screenshot_project_new.png differ diff --git a/docs/images/screenshot_userprofile.jpg b/docs/images/screenshot_userprofile.jpg new file mode 100644 index 0000000..bf75f47 Binary files /dev/null and b/docs/images/screenshot_userprofile.jpg differ diff --git a/docs/images/whitepaper/OLL2024_42.jpg b/docs/images/whitepaper/OLL2024_42.jpg new file mode 100644 index 0000000..405f092 Binary files /dev/null and b/docs/images/whitepaper/OLL2024_42.jpg differ diff --git a/docs/index.md b/docs/index.md index aae0e56..a8abaf2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ Driven By Data
-**Dribdat** (from "driven by data") is an open source web application, featuring a playful ideation and challenge board to help organize short sprints, co-creative sessions, hackdays and [awesome hackathons](https://meta.dribdat.cc/event/2) with batteries included. See our [roadmap](https://github.com/orgs/dribdat/projects/8/views/2?pane=issue&itemId=89596986) 🔜 sign up to get invited to beta releases at *[EveryHack.day](https://everyhack.day)* +**Dribdat** (from "driven by data") is an open source web application, featuring a playful ideation and challenge board to help organize short sprints, co-creative sessions, hackdays and [awesome hackathons](https://meta.dribdat.cc/event/2) with batteries included.
@@ -17,8 +17,14 @@ Driven By Data Screenshot of dribdat
+
-# Purpose +
See our [roadmap](https://github.com/orgs/dribdat/projects/8/views/2?pane=issue&itemId=89596986) 🔜 sign up for the beta @ [EveryHack.day](https://everyhack.day) + +
+ + +## Purpose Built around Web-friendly standards like [Schema.org](https://schema.org) and [Frictionless Data](https://frictionlessdata.io), Dribdat is an (MIT licensed) part of an open source ecosystem, featuring bootstraps (authentication, file uploading, data import/export, etc.), useful workflows (announce an event - publish challenges - form teams - develop projects) and channels (social media sharing, digital signage, summary reports). diff --git a/docs/usage.md b/docs/usage.md index 5924054..5a62e5a 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -3,29 +3,34 @@ User handbook --- -This document explains the basic functions of `dribdat`, an open source platform for data-driven team collaboration (such as *[Hackathons](https://hackathon.guide/)*). It is a FAQ covering the basic usage of the application. For more background see [ABOUT](about), and for technical details visit the [README](https://github.com/dribdat/dribdat#dribdat). +This page explains Dribdat, an open source platform for data-driven team collaboration (such as *[Hackathons](https://hackathon.guide/)*), covering the basic usage of the application. For more background see [ABOUT](about), and for technical details visit the [README](https://github.com/dribdat/dribdat#dribdat). For a printable version of this document see [📄 Handbook for hackathons powered by Dribdat](https://docs.google.com/document/d/e/2PACX-1vR5Gv5NA3pkls0FRufC0dg-blkOhSo1LMX58pSNtj0FhZq1ImmLw0cIwmla_hiZaxtP8tnzJQQgZg94/pub) +# Dear Participant -**dribdat** works as a website and project board for running exciting, productive events, and allows organizers and participants to collect their project details in one place, displaying the challenges and projects in Web dashboards, and plugging in community tools such as [Discourse](https://www.discourse.org/) or [Slack](http://slack.com) - or using the [remote API](#api) for custom frontends or [chatbots](https://github.com/datalets/dridbot) to enhance the hackathon. +**Dribdat** (from Driven by Data) works as an online multitool and project board, incorporating best practices from community building, such as templates for 🌳beginner 😄intermediate 🏀advanced level challenges, a 7-stage process for effective data-driven projects, connectivity to popular collaboration platforms, and time-tracking utilities. -It incorporates tools and best practices from 10 years of community building and open data activism, such as templates for 🌳beginner 😄intermediate 🏀advanced level challenges, a 7-stage process for data-driven projects, connectivity to popular collaboration platforms, and time-tracking utilities. +So what are we waiting for? Let's get started! -As it helps us - we hope it will help you to contribute to open projects, be a better (team) player, and make the most of a blank canvas and creative constraints. - -## Quickstart +## Quick start Open the page of an event, log in and create a user **Profile**. Then you can explore the existing challenges at your event. Keep an eye on the unfilled Roles (🖍️Designer ⚙️Enabler 💡Facilitator etc.) that are shown on the bottom of the project page, if you are not sure which team you should support. You can then leave a **Comment** or **Join** the challenge. -Or, if the organisers permit it, you may also be able to submit a **New** challenge, along with a summary of your idea. This could also be a "fork" of an existing challenge, as sometimes multiple teams would like to work on the same idea. Once you have a project page, you and any of your team members can click the **Join** button to start to contribute. +![](images/screenshot_userprofile.jpg) + +Before the event starts, you may also be able to submit a **New** challenge, along with a summary of your idea. This could be linked to a supported design tool or code repository. Once you have a project page, you and any of your team members can click the **Join** button to make changes and contribute updates. -A typical dribdat-powered event (this is [GLAMhack 2022](https://hack.glam.opendata.ch/)) has a variety of challenges and projects at different stages, which you can explore in a hexagonal grid: +![](images/screenshot_project_new.png) + +A typical Dribdat-powered event (this is from [GLAMhack](https://hack.glam.opendata.ch/) - the Swiss Open Culture Data hackathon) has a variety of challenges and projects at different stages, which you can explore in a hexagonal grid: ![](images/glamhack.jpg) ### Leap into action -Use your project page to document what makes your ideas tick. Post a creative 30-second **Pitch** using plain text or [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) - there is an editor you can activate which helps you learn this widely used formatting style. You can add links to sound or video clips, embed documents or a slideshow hosted on [Speaker Deck](https://speakerdeck.com/) and similar. Content from many other [supported sites](https://oembed.com/#section7) will turn into a live preview. +Use your project page to document what makes your ideas tick. Post a creative 30-second **Pitch** using plain text or [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) - there is an editor you can activate which helps you learn this widely used formatting style. Enable **Presentation mode** to turn your pitch into slides, or upload a PDF if you prefer. + +You can add links to sound or video clips, embed documents or a slideshow hosted on [Speaker Deck](https://speakerdeck.com/) and similar. Content from many other [supported sites](https://oembed.com/#section7) will turn into a live preview. The picture below explains the various parts of a typical challenge or project page: diff --git a/livemark.yaml b/livemark.yaml index 3625781..665c672 100644 --- a/livemark.yaml +++ b/livemark.yaml @@ -17,14 +17,14 @@ pages: items: - path: docs/index name: Intro - - path: docs/deploy - name: How to install - path: docs/usage - name: User guide + name: User handbook - path: docs/organiser name: Organiser guide + - path: docs/deploy + name: How to install - path: docs/contribute - name: Developer guide + name: How to contribute - path: docs/whitepaper name: Whitepaper - path: docs/about