Skip to content

Requirements

Jump to bottom
Giovanni Sce edited this page Dec 13, 2020 · 39 revisions

These requirements are still been discussed.

We can divide the requirements in MVP and Post-MVP or other priority approach.

Landing Page

  • This is temporary until the site is live
  • A user can enter their email and send it to the API/subscribe endpoint
  • Page comes back with success or error message (including "wrong format" and "already subscribed")
  • The "want to join the CTI" button goes to https://www.hackforla.org/projects/civic-tech-index
  • Social media icons go to the "social media" page

Home Page

  • Learn Mode goes to the "About" page
  • See how the civic tech index is used by:
  • For MVP, the list of organization logos is built only in UI, they are the most significant (by which criteria?) organizations in CTI (?). Clicking will go to the organization projects page (the Contributor)
  • View More Contributors" goes to Contributors
  • Trending Topics For MVP, the list is manually created in the UI. Post MVP, we'll need an API to return the items (the most popular searches [or topics?])

test

iii

About

  • Shows a video with an overview of CTI tools
  • Tag Your Project goes to Tag Generator

FAQ

  • Upon landing on this page, the user sees the 5 most common (accessed) answers (and their questions). The UI invokes the API/faqs
  • The user can search in the FAQs in the database (typeahead is not part of MVP). The UI invokes the API/faqs/search (endpoint to confirm)
  • Question: How does the DB search works if the user submit more than one word?
  • When the user expands/clicks on one of the FAQ returned, the API/faqs/{id}/increment_counter is called and the counter for the specific faq is increased in the database. This is how the system determines the most common faqs.
  • Question: What if the search doesn't return any answer? It could be a popular "search" too
  • Contact Us will display a Google form (fields?) for the user to submit their question.
  • Question: What happens when the user submits the form?

Contributors / Organizations / Directory

  • Upon landing on this page, the UI calls the API/organizations which returns all the Organizations in as a tree (parent/children) and sorted alphabetically (within each level of the tree).

  • The UI Search box filters the data within the UI

  • Clicking on an unaffiliated contributor will go to the Organization external page

  • Clicking on an affiliated child (leaf of the tree) contributor will go to the Individual Contributor CTI page (

  • If a user wants to add an Organization

    • For MVP the process is:
    • A Modal window will ask: Have you used the wizard to add "civictechindex" topic tag and relevant tags to all of your projects?
      • No => Takes user to the Tag Generator wizard to add tags required by CTI
      • Yes => Goes to a Google form to submit the Organization information to civictechindex@gmail.com
      • CTI staff will review and approve (via github issue) to enter the new Organization in the CTI database organization table
    • Post MVP, there will be a page with a form to submit the Organization information and trigger the CTI staff review (the new Organization can be saved in the database but with a "not-active" flag)

  • The Organization table should have a field for topic_tag (the open-okland vs openokland, the value that the organization uses in its github repository)

Individual Contributor / Organization

  • From the list of organizations returned by the search (or scrolling through the initial list) the user can click on a specific organization
  • Upon landing on the page, the UI queries Github to retrieve all the repositories using the topic tag that matches the organization name
  • If arriving from Contributors page, the UI stores the parent and grandparent of the organization. Otherwise, the UI will invoke the API/organizations/{name} to retrieve this information from the CTI database
  • Clicking the links (provided when creating an Organization in CTI database) will open the respective external pages (home or github typically).
  • The right side box will show all the repositories not in the organization Github page but that use the organization topic tag (the "name"?)
    • Clicking one of these URL will open the specified repository
  • All the Organization Github projects (loaded upon landing on the page) will be shown in the page (with pagination if necessary) with the [detailed information[(project) (number of issues, project description, URL, topics etc.)
  • Can a project belong to more than one organization?

Project Card

This portion of a page is shown within the Contributor page or as result of search for projects and it displays the details of one project/repository.

  • All the data is retrieved from Github via a call to Github API ...
  • Display a link to the Github repository
  • Affiliation topic tags are the one typically of the organization parent/owner of the project/repository
  • Project Language (English, Spanish or others ... don't seem to be available from Github); Should we remove it?
  • Programming Language(s) is usually determined by Github, but there can be no-coding repository (just documentation); Question: display or not the label?
  • If there is no location returned from Github, don't display even the label
  • Topic Tags are the one that identify the issue(s) that the project aim at addressing

Tag Generator

This is the feature by which a github repository admin or contributor can add a repository (project) to the Civic Tech Index (CTI) with standard and custom tags. In fact, the process to include a repository within the CTI is based on adding CTI standard tags (civictechindex tag will be the topmost criteria to retrieve CTI projects).

The set of pages of this feature starts with a question on whether the project to add belong to an organization already registered in CTI or not:

  • Yes
    • From a dropdown showing all the 'CTI' Organization (retrieved with the <API/organizations call) the user needs to select one Organization
    • After selecting an Organization, the user inputs a Github repository (to append to the Github Organization page) name and click the "Search" button
  • No
    • ...?
  • The search goes to Github to retrieve the repository
  • If the repository is not found an error message should be displayed on the same page
  • If the repository is found, the page shows the topic tags retrieved from Github (?) and a radio button asking if the user wants to add more topic tags
  • The system should also display automatically generated tags regarding the "affiliation" like "code-for-all", "code-for-africa", etc...
  • If the user selects "Yes"
    • The system suggests some topic tags (based on the words in the repository name and/or something else?). A light action click allow to add one tag and the user can add multiple just simply typing (no typeahead?)
    • The system will show a button "Generate Tags" which will go to the next step (below) or keep adding tags. There are also buttons to reset the tags or reset the form.
  • If the user selects "No"
    • ...?
  • When the user click the "Submit" button, the system will show a page describing the process to enter the tags in Github (for MVP)

The Tag Generator adds automatically the standard tags:

  • If the repository belongs to a known organization (and the user enters it) the Tag Generator adds tags like "civictechindex", "codeforall", "codeforafrica" and "codefortanzania" for example
  • Otherwise it will add only "civictechindex"

The user can then add additional tags that signify the purpose of the project or its location or other characteristics such as "food-insecurity" or "homeless-outreach".

The standard tags can not be removed.

The front-end should suggest the tag when a user starts to type a custom tag. The system should present a list of existing tags that match what the user is typing, for example as the user types in food, the system should display food-insecurity, food-pantry, food-bank, collect-food, etc.

The system should encourage the user to reuse an existing tag rather than create a new one.

When the user clicks "Submit" the system saves the tags in (github or database?). Can the user enter anything else?

The user should be able to modify or delete the custom tags later on.

Technical Design

Search Projects

Search in Github for all the project with civictechindex topic (automatically added by the system) and additional search terms (in "AND") that the user enters.
This page can also be reached from the "Trending Topics" (clicking one topic).

  1. In the search box the user can type anything they want to search by. From location, to spoken language, from programming language to area of concern or issue.
  2. The system will return the list of projects that match at least one search keyword. The search keywords are interpreted in OR (as opposed to AND). The list of projects should be sorted by ...
  3. The user can further refine the result by programming language, affiliation (organization), number of open issues, last update timespan, location.

The list of checkboxes to check (to refine the result) doesn't depend on the list of retrieved projects (it's kind of static).
The refining of the result is performed in the front-end (or back-end?)

  1. Clicking on the project URL (or icon or square) should open the project git repository page.

Search filters: Programming languages: From projects returned from GH

Github has various API like
https://api.github.com/search/repositories?q=tetris+language:assembly&sort=stars&order=desc
https://api.github.com/search/repositories?q=topic:ruby+topic:rails
https://api.github.com/search/labels?repository_id=64778136&q=bug+defect+enhancement

More sophisticated Github queries are available

Radical Collaboration (Support Us?)

This is a set of pages

  • How to do it: I don't see a screenshot
  • Donate: Back-end link to a donations platform? Link to CfA donations page?
  • Share CTI: Does it need a page? Or just the social media icons? How does it (back-end) work when clicking on an icon?
    It is a page with various widgets to post about CTI
  • Volunteer with us: Link to a form, which fields in the form, where does the form go? Plus link to a project team page (not github?)
  • FAQ: faq
Clone this wiki locally