SeasonOfDocs: Difference between revisions

Latest revision as of 09:57, 7 August 2024

Welcome!

Open Food Facts is a non-profit open source and open data project with a massive impact on the food and health of millions of people across the world, and we need your help to make this impact even bigger in many more parts of the world!

Open Food Facts is a participant organization for the Google Season of Docs 2022: see GSOD2022 API documentation

Getting started

If you would like to work on the Open Food Facts documentation project during the Google Season of Docs, make sure to join the Open Food Facts community on Slack, introduce yourself there and get familiar with the project.

A good way to do that is to open your fridge or cupboard to find a food item to scan with our Android or iOS application. Open Food Facts works like Wikipedia. The food product may already be in the database with its data completed. If it’s present, you will get valuable information about its nutritional quality (Nutri-Score) or its level of food processing (NOVA). If it’s not present yet, please take some pictures and add it!

Submit your statement of interest via email to contact -AT- openfoodfacts.org put GSOD in the subject, by the 9th of may, 2022: present yourself, your skills and experiences, and your personal approach to the project.

2022 project

Have a complete OpenAPI compliant documentation for the Open Food Facts API

About your organization

Open Food Facts is the "wikipedia of food".

Make better food choices for your health and for the planet

It's a database of food and cosmetic products with all the data you can find on product labels.

Food additives, allergens, packaging codes: Open Food Facts helps you make sense of the fine print on products labels. Also, you can easily compare products in 3-clicks, so that you can make more informed choices.

Made by everyone

Open Food Facts is a non-profit association of volunteers. Since 2012, 25000+ contributors have added 2 Million+ products from 180 countries using the Android or iPhone apps to scan barcodes and upload pictures of products and their labels. We helped foster the Nutri-Score across Europe which is now present on physical projects, and we’re doing the same for the planet with Eco-Score.

For everyone

Data about food and cosmetics is of public interest and has to be open. In addition to the official app, Open Food Facts is a platform for developers, and there are more than 150 re-uses of the data in many different ways: many nutrition apps to eat better, food inventory apps to prevent waste, research by health and nutrition scientists, investigations by journalists, educational games etc.

With a good documentation

As a result, many users (developers, scientists, innovators…) use and rely heavily on the Open Food Facts API. The better documentation we have, the more reuses we'll get, and the more apps we'll get to contribute back data to this common good.

About your project

Your project’s problem

Many people rely on the Open Food Facts API to help transform the food system. Ensuring that the API documentation is OpenAPI compliant - but also clear and readable - will promote the development of new applications based on the Open Food Facts database, scientific reuses, and improve the quality and quantity of data. This, in turn, will increase the number of conscious customers checking via apps the nutrition values of the food products they purchase and support Open Food Facts’ vision of making nutritional information available to everyone.

As a result, we made lowering the API barrier to entry and developing API data contributions two of our 2022 priorities. This project will thus help us reach those goals.

Your project’s scope

Expected outcomes:

Refresh the Open Food Facts API and make it OpenAPI compliant

Audit the existing documentation and create a friction log, especially around the API itself, and the tools used to maintain it.
Refresh the Open Food Facts API based on feedback/exchanges with the community
Extend the documentation with all the new routes and APIs listed in https://github.com/openfoodfacts/api-documentation
Ensure all existing routes are compliant with best practices for OpenAPI that allow for SDK generation, testing…
Participate in leveling up our API game and best practices, along with the core Open Food Facts team
(stretch goal) Set up a GitHub Actions CI pipeline with mentors to convert the doc to Open API (and then to OpenAPI generated SDKs)

Estimated time on the project: 200 hours (25 days on 5 month).

Getting started now tasklist

The following things can help you select a project and prepare your idea:

Join our chat room
Introduce yourself in the #api-documentation channel
Join the channels related to the countries you're interested in
It is important to first familiarize with the API documentation and project.
Try one of our "good first issues" on GitHub
Please, go through the available documentation and direct your questions to the Slack chat.
As you learn, it is also a good idea to propose updates to the documentation.
If you have not worked before with Git Branching, we encourage you to visit this web: https://learngitbranching.js.org/
Fill our upcoming introduction survey (it is NOT an application form)

2022 project management

See GSOD timeline.

@@ Line 1: / Line 1: @@
-Open Food Facts is not just a mobile app that's the Wikipedia for food. It's also a very valuable platform for developpers, scientists and others.
+== Welcome! ==
+Open Food Facts is a non-profit open source and open data project with a massive impact on the food and health of millions of people across the world, and we need your help to make this impact even bigger in many more parts of the world!
+=== '''Open Food Facts is a participant organization for the Google Season of Docs 2022: see [[GSOD2022 API documentation]]''' ===
-=== Create a developper page for OpenFoodFacts.org ===
+== Getting started ==
+If you would like to work on the Open Food Facts documentation project during the Google Season of Docs, make sure to join the Open Food Facts community on Slack, introduce yourself there and get familiar with the project.
-Goal: onboard prospective developpers and people wanting to use Open Food Facts in their app
+A good way to do that is to open your fridge or cupboard to find a food item to scan with our Android or iOS application. Open Food Facts works like Wikipedia. The food product may already be in the database with its data completed. If it’s present, you will get valuable information about its nutritional quality (Nutri-Score) or its level of food processing (NOVA). If it’s not present yet, please take some pictures and add it!
-- basic information about getting started as a contributor to the open source project
+'''Submit your statement of interest''' via email to contact -AT- openfoodfacts.org put GSOD in the subject, '''by the 9th of may, 2022''': present yourself, your skills and experiences, and your personal approach to the project.
-- rules around licence agreements, processes for pull requests and reviews, building the project, pointers to the Slack room, the API docs…
-url: https://world.openfoodfacts.org/developers
+== 2022 project ==
-source code: https://github.com/openfoodfacts/openfoodfacts-server
-=== Build a dedicated documentation site ===
+=== Have a complete OpenAPI compliant documentation for the Open Food Facts API ===
-Build a central documentation site on a platform to be decided by the technical writer and open source mentor, and publish an initial set of basic documents on the site. Examples of platforms include:
+=== About your organization ===
+'''Open Food Facts is the "wikipedia of food".'''
-* Read the Docs
+Make better food choices for your health and for the planet
-* A static site generator such as Hugo, Jekyll, Sphinx, and more
-* GitHub Pages
-=== Write conceptual overviews of the Open Food Facts products ===
+It's a database of food and cosmetic products with all the data you can find on product labels.
-. Write a conceptual overview and introduction to the Open Food Facts server
+Food additives, allergens, packaging codes: Open Food Facts helps you make sense of the fine print on products labels. Also, you can easily compare products in 3-clicks, so that you can make more informed choices.
-- Explain the high level goals, the architecture, the libraries used, the known limitations and the high level wishlist
-future url: https://docs.openfoodfacts.org
+'''Made by everyone'''
-. Write a conceptual overview and introduction to Open Food Facts mobile app for iOS
+Open Food Facts is a non-profit association of volunteers. Since 2012, 25000+ contributors have added 2 Million+ products from 180 countries using the Android or iPhone apps to scan barcodes and upload pictures of products and their labels. We helped foster the Nutri-Score across Europe which is now present on physical projects, and we’re doing the same for the planet with Eco-Score.
-- Explain the high level goals, the architecture, the libraries used, the known limitations and the high level wishlist
+'''For everyone'''
-source code: https://github.com/openfoodfacts/openfoodfacts-ios
+Data about food and cosmetics is of public interest and has to be open. In addition to the official app, Open Food Facts is a platform for developers, and there are more than 150 re-uses of the data in many different ways: many nutrition apps to eat better, food inventory apps to prevent waste, research by health and nutrition scientists, investigations by journalists, educational games etc.
-. Write a conceptual overview and introduction to Open Food Facts mobile app for Android
+'''With a good documentation'''
-- Explain the high level goals, the architecture, the libraries used, the known limitations and the high level wishlist
-source code: https://github.com/openfoodfacts/openfoodfacts-androidapp
+As a result, many users (developers, scientists, innovators…) use and rely heavily on  the Open Food Facts API. The better documentation we have, the more reuses we'll get, and the more apps we'll get to contribute back data to this common good.
-. Write a conceptual overview and introduction to the Open Food Facts API
+=== About your project ===
-- Explain the high level goals, the architecture, the libraries used, the known limitations and the high level wishlist
-- Write guidelines on how to implement the API to ensure a sound and safe user experience
-source code: https://github.com/openfoodfacts/openfoodfacts-server
+==== Your project’s problem ====
-current documentation: https://en.wiki.openfoodfacts.org/
+Many people rely on the Open Food Facts API to help transform the food system. Ensuring that the API documentation is OpenAPI compliant - but also clear and readable -  will promote the development of new applications based on the Open Food Facts database, scientific reuses, and improve the quality and quantity of data. This, in turn, will increase the number of conscious customers checking via apps the nutrition values of the food products they purchase and support Open Food Facts’ vision of making nutritional information available to everyone.
+As a result, we made lowering the API barrier to entry and developing API data contributions two of our 2022 priorities. This project will thus help us reach those goals.
-=== Refactor the "How to add a product" documentation ===
+==== Your project’s scope ====
+Expected outcomes:
-* Refresh screenshots and instructions to match the new UI
+Refresh the Open Food Facts API and make it OpenAPI compliant
-* Automate screenshot generation across languages
-# Create a documentation of the advanced features of Open Food Facts for scientists, journalists…
+* Audit the existing documentation and create a friction log, especially around the API itself, and the tools used to maintain it.
+* Refresh the Open Food Facts API based on feedback/exchanges with the community
+* Extend the documentation with all the new routes and APIs listed in <nowiki>https://github.com/openfoodfacts/api-documentation</nowiki>
+* Ensure all existing routes are compliant with best practices for OpenAPI that allow for SDK generation, testing…
+* Participate in leveling up our API game and best practices, along with the core Open Food Facts team
+* (stretch goal) Set up a GitHub Actions CI pipeline with mentors to convert the doc to Open API (and then to OpenAPI generated SDKs)
-* Document the advanced search feature, and the graph generation, with examples
+Estimated time on the project: 200 hours (25 days on 5 month).
+=== Getting started now tasklist ===
+The following things can help you select a project and prepare your idea:
-=== Document the Open Food Facts API ===
+* Join our chat room
+* Introduce yourself in the #api-documentation channel
+* Join the channels related to the countries you're interested in
+* It is important to first familiarize with the API documentation and project.
+* Try one of our "good first issues" on GitHub
+* Please, go through the available documentation and direct your questions to the Slack chat.
+* As you learn, it is also a good idea to propose updates to the documentation.
+* If you have not worked before with Git Branching, we encourage you to visit this web: <nowiki>https://learngitbranching.js.org/</nowiki>
+* Fill our upcoming introduction survey (it is NOT an application form)
-. General
+== 2022 project management ==
+See [https://developers.google.com/season-of-docs/docs/timeline GSOD timeline].
-The Open Food Facts API has grown organically through the years, and has been documented as we go, but not in a systematic way. New practices like automatic API generation from the Code could be added.
+[[Category:Project]]
+[[Category:Documentation]]
-https://en.wiki.openfoodfacts.org/API
-. READ
-The READ part of the API is very important for the official client, as well as for apps who send direct calls from their users to the API (provided volume stays reasonable).
-The project can be divided in one part for the images, one for the data.
-https://en.wiki.openfoodfacts.org/API/Read
-. WRITE
-The WRITE part is very important to let apps send images and data contributed by their users, to Open Food Facts. The better documented, and the easier it is to implement contribution within 3rd party apps, the more images and data we'll get, the faster we'll have full food transparency worldwide.
-The project can be divided in one part for the images, one for the data.
-https://en.wiki.openfoodfacts.org/API/Write
-. Automatic generation
-Add documentation within the code to generate documentation and SDKs automatically. Automatic generation from code with things like Swagger would be very interesting
-=== Automate screenshot generation of the mobile and web apps ===
-* Refresh screenshots and instructions to match the new UI for the web tutorial (and possibly automate screenshot generation)
-* On mobile (Android), finish to automate screenshot generation across languages, and add support for framing, text…
-* On mobile (iOS), automate screenshot  generation across languages, and add support for framing, text…
-source code: https://github.com/openfoodfacts/openfoodfacts-ios
-source code: https://github.com/openfoodfacts/openfoodfacts-androidapp
-=== Document how to install the Open Food Facts server ===
-=== Document a "perfect" version 2 of the API before we code it ===