wbrawner/ffc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

WIP: first documentation drafts

Browse source 
Co-authored-by: Niko Lockenvitz <nl@nikolockenvitz.de>
This commit is contained in:
Rene Fischer 2020-07-08 14:00:59 +02:00
parent 33041ef140
commit e97c1198bf
No known key found for this signature in database
GPG key ID: 5D8E12AC54D3C1B5
7 changed files with 193 additions and 115 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

116
README.md
View file

@ -3,12 +3,6 @@
![Build and Deploy](https://github.com/dhbw-ffc/ffc/workflows/Build%20and%20Deploy/badge.svg)
- [Documentation](#documentation)
- [Introduction](#introduction)
- [Terminology](#terminology)
- [Leaning Progress and Rating of Cards](#leaning-progress-and-rating-of-cards)
- [Random Card Selection](#random-card-selection)
- [File Format for External Data Sources](#file-format-for-external-data-sources)
- [Internal Storing of Decks, Cards and Learning Progress](#internal-storing-of-decks-cards-and-learning-progress)
- [Vue](#vue)
- [Why Vue?](#why-vue)
- [Project setup](#project-setup)
@ -20,115 +14,7 @@
## Documentation
### Introduction
Of course there are already a lot of flashcard apps, but they all lack a feature we consider very convenient.
The feature we are talking about is using multiple selected card decks in one session without switching between decks manually.
Our goal with this app is to provide a simple and easy to use Progressive Web App foundation.
This foundation consists of a simple storing approach for Q&A-pairs as well as a progression system to support a users learning journey.
In general we want to make it possible to add/import decks as easy as possible to enable anyone to use the app for their purposes.
To understand how it all works please read this README, we try to cover our every thought.
If you have any questions about our ideas, feel free to contact us.
### Terminology
Decks can be imported via files.
Files can be stored locally or accessed online via an URL.
Each file contains multiple decks.
Each deck is identified by a short name / id (only inside this file).
It then contains some meta data (full name, description, ...) and multiple cards (questions with corresponding answers), each identified by some incrementing number (the next value is stored in the meta data so that there are no collisions when cards are deleted).
You can find the file format for such files below.
A card (question-answer-pair) is uniquely identified by the data source identifier (e.g. URL where the file is hosted, local filepath, ...), the deck short name / id and the id of the card itself (inside the deck).
### Leaning Progress and Rating of Cards
The learning progress is stored locally in the app.
After revealing an answer, the user can rate how hard/easy it was (e.g. on a scale from 1 to 5; 1=hard, 5=easy).
For each card an array of objects like ``{ "timestamp": "...", "rating": 50 }`` is stored.
Internally the rating is always stored on a scale from 0 to 100 (indepentend of what the users sees and selects; makes more precise adjustments easier in the future).
The rating which is displayed to the user must be mapped, e.g. 1 &rarr; 0, 2 &rarr; 25, ..., 5 &rarr; 100.
### Random Card Selection
The user can select one or multiple decks for learning (and maybe limit time or number of cards).
The selection of cards is done by an algorithm, which can be replaced or adjusted.
Our first proposal is as follows:
* we downgrade the rating of each card based on time and rating when user rated it the last time
* this leads to a virtual rating for each card
* when the next card needs to be displayed, we choose randomly from all the cards based on the virtual rating (low rating = higher probabilty of being chosen)
### File Format for External Data Sources
````json
{
"meta": {
"author": "Name of the Author",
"...": "..."
},
"decks": {
"deck_short_name": {
"meta": {
"deck_name": "Full Name of the Deck",
"description": "Description",
"next_card_id": 3,
"...": "..."
},
"cards": {
"0": {
"q": "question",
"a": "answer"
},
"2": {
"q": "question",
"a": "answer"
}
}
},
"...": {}
}
}
````
You can find an example file and a command line interface to create and edit such files in the [cli folder of this repository](cli).
Such files can be either loaded as a local file or from a URL.
The latter one can easily be done if CORS headers are present but it might be that not everyone is able to configure this (e.g. static file server).
See [no-cors.md](docs/no-cors.md) for ideas how Same-origin policy can be bypassed without CORS.
### Internal Storing of Decks, Cards and Learning Progress
````json
{
"decks": [{
"id": 1,
"selected": false,
"name": "Name of the Deck (uses deck_name or deck_short_name as a fallback)",
"meta": {
"file": {
"author": "Name of the Author",
"...": "..."
},
"deck": {
"short_name": "Short Name of the Deck",
"name": "Full Name of the Deck",
"description": "Description",
"next_card_id": 3,
"...": "..."
}
},
"cards": [
{
"id": 1,
"q": "question",
"a": "answer",
"r": [
{ "t": "Timestamp When This Card Has Been Rated", "r": 50 },
{ "t": 1590866520000, "r": 99}
]
},
{ "...": "..."}
]
},
{ "...": "..."}
]
}
````
See [Documentation](docs/README.md).
## Vue

123
docs/README.md Normal file
View file

@ -0,0 +1,123 @@
# Documentation
## Other files
With the following documents we try to express our ideas and our thought process while creating this project.
Please take a look at the documents sorted by topics.
- [Idea](idea.md)
- [Architecture](architecture.md)
- [Technology](technology.md)
- [Montization](monetization.md)
- [Backlog](backlog.md)
## Introduction
Of course there are already a lot of flashcard apps, but they all lack a feature we consider very convenient.
The feature we are talking about is using multiple selected card decks in one session without switching between decks manually.
Our goal with this app is to provide a simple and easy to use Progressive Web App foundation.
This foundation consists of a simple storing approach for Q&A-pairs as well as a progression system to support a users learning journey.
In general we want to make it possible to add/import decks as easy as possible to enable anyone to use the app for their purposes.
To understand how it all works please read this README, we try to cover our every thought.
If you have any questions about our ideas, feel free to contact us.
## Terminology
Decks can be imported via files.
Files can be stored locally or accessed online via an URL.
Each file contains multiple decks.
Each deck is identified by a short name / id (only inside this file).
It then contains some meta data (full name, description, ...) and multiple cards (questions with corresponding answers), each identified by some incrementing number (the next value is stored in the meta data so that there are no collisions when cards are deleted).
You can find the file format for such files below.
A card (question-answer-pair) is uniquely identified by the data source identifier (e.g. URL where the file is hosted, local filepath, ...), the deck short name / id and the id of the card itself (inside the deck).
## Learning Progress and Rating of Cards
The learning progress is stored locally in the app.
After revealing an answer, the user can rate how hard/easy it was (e.g. on a scale from 1 to 5; 1=hard, 5=easy).
For each card an array of objects like ``{ "timestamp": "...", "rating": 50 }`` is stored.
Internally the rating is always stored on a scale from 0 to 100 (indepentend of what the users sees and selects; makes more precise adjustments easier in the future).
The rating which is displayed to the user must be mapped, e.g. 1 &rarr; 0, 2 &rarr; 25, ..., 5 &rarr; 100.
## Random Card Selection
The user can select one or multiple decks for learning (and maybe limit time or number of cards).
The selection of cards is done by an algorithm, which can be replaced or adjusted.
Our first proposal is as follows:
* we downgrade the rating of each card based on time and rating when user rated it the last time
* this leads to a virtual rating for each card
* when the next card needs to be displayed, we choose randomly from all the cards based on the virtual rating (low rating = higher probabilty of being chosen)
## File Format for External Data Sources
````json
{
"meta": {
"author": "Name of the Author",
"...": "..."
},
"decks": {
"deck_short_name": {
"meta": {
"deck_name": "Full Name of the Deck",
"description": "Description",
"next_card_id": 3,
"...": "..."
},
"cards": {
"0": {
"q": "question",
"a": "answer"
},
"2": {
"q": "question",
"a": "answer"
}
}
},
"...": {}
}
}
````
You can find an example file and a command line interface to create and edit such files in the [cli folder of this repository](cli).
Such files can be either loaded as a local file or from a URL.
The latter one can easily be done if CORS headers are present but it might be that not everyone is able to configure this (e.g. static file server).
See [no-cors.md](docs/no-cors.md) for ideas how Same-origin policy can be bypassed without CORS.
## Internal Storing of Decks, Cards and Learning Progress
````json
{
"decks": [{
"id": 1,
"selected": false,
"name": "Name of the Deck (uses deck_name or deck_short_name as a fallback)",
"meta": {
"file": {
"author": "Name of the Author",
"...": "..."
},
"deck": {
"short_name": "Short Name of the Deck",
"name": "Full Name of the Deck",
"description": "Description",
"next_card_id": 3,
"...": "..."
}
},
"cards": [
{
"id": 1,
"q": "question",
"a": "answer",
"r": [
{ "t": "Timestamp When This Card Has Been Rated", "r": 50 },
{ "t": 1590866520000, "r": 99}
]
},
{ "...": "..."}
]
},
{ "...": "..."}
]
}
````

0
docs/architecture.md Normal file
View file

4
docs/backlog.md Normal file
View file

@ -0,0 +1,4 @@
# Backlog
Ideas we want to implement in the future, but did not have enough time to implement or work out completely.

6
docs/idea.md Normal file
View file

@ -0,0 +1,6 @@
# The idea behind Fancy Flashcard
Fancy Flashcard (FFC) originated from the idea of combining the ease of use of index cards and their flexibility.
With normal index cards you can simply mix the learning decks you want, no matter the topic.
We tried to do the same with FFC by allowing the user to combine two or more decks for a learning session.

59
docs/monetization.md Normal file
View file

@ -0,0 +1,59 @@
# Monetization
Sooner or later every app publisher thinks about monetization in some form.
A vast majority chooses an ad based monetization system.
On the one hand that doesn't make much sense because we prefer an open source model and anyone could fork the repository and diable ads.
On the other hand users can easily install addons in their browsers to block ads.
Additionally such an ad based monetization system often leads to an app with around 50% of the available display area filled with ads.
Because of this many users despise this sort of monetization and will opt to other apps instead, especially if the app has a small user base or is easily replaceable.
We try to combat this with a few ideas of our own.
## Educational App
Our first idea is about education and ability to easily access it.
Because of this we want to create specialized versions of the app with pre-installed decks or deck selection menus for every customer.
Customers can be private companies and public institutions like schools or universities that pay a comparably small fee to have this web app adjusted to their needs and get help rolling it out.
This repository being open source and under the MIT License will also be available for those customers to adjust on their own without any cost connected to it.
Our goal with this is to accumulate more users and introduce the app as the de facto standard for educational purposes.
How does it work though?
It's pretty simple, we create a deck selection instead of the deck creator on the import page.
This deck selection will be fed by a JSON file hosted by us or the company/school and will include all decks created by the school.
Users will simply choose a deck they want and add it to their own collection.
To avoid misuse we could disable the URL import and only allow users to choose the given decks.
Ease of use is the focus of an educational app and users should enjoy using it.
Because of this our long term goal would be to enable the app to be used for educational purposes simply by submitting a code created for your company or school.
With this idea we eliminate the need of specialized apps as well as a lot of support and thus lower the cost of development in the long term.
## Curated Decks
Another monetization idea are curated decks.
With curated decks we create a space for companies and users to get their decks featured and seen by every user in the app.
These decks will use the same deck selection as the educational app proposes.
This kind of deck library will use a static url to get possible decks that we think are worth your time or have a sponsor and are not contrary to public morality.
In the end we might offer others the possibility to sell decks to users for a small fee so that we can get a commission every time someone buys a deck.
This would also help to generate income without the need to maintain a large pool of staff members.
If we give users the opportunity to earn money with our app, they will do their part to make the app successful and boost their and thus our profits.
A deck library is one of the few things we want to add in the future and can be used in many different ways, so curated decks could be the first monetization idea we try.
## Arrange contact to private tutors
We also thought about some model similar to ads but more focused on the subject of learning.
Users could give their consent to see suitable private tutors for certain subjects they are struggling with.
We could then get a small commision for connecting students with a tutor.
This can also be used together with our educational app approach where older students could offer help for younger ones.
This would also have the advantage that subjects are specific for one institution/school.
## Closing Words
The app will always be open source and free for everyone to fork and create an own version improving what we created.
Because of this we encourage everyone to contribute to this repository in order to create the best application possible.
Ads keep getting more intrusive and are used to get a perfect digital copy of you to target you with even more specialized ads.
We believe apps should not see users as the product they are trying to sell to customers (e.g. advertisers) and that is why we do not want to incorporate any sort of ads in our design.
With our design the focus is shifted to the users anonymity and safety.
They should feel free to learn new or improve their skills.
The constant fear of collecting personalized data and the misuse of it will hinder their learning ability and thus be contraproductive for our purpose.

0
docs/technology.md Normal file
View file