Difference between revisions of "Documentation"

From Open Food Facts wiki
Jump to navigation Jump to search
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
=== Documentation ===
 
=== Documentation ===
 
* [[Product_Opener_documentation|Product Opener documentation (web)]]
 
* [[Product_Opener_documentation|Product Opener documentation (web)]]
−
* [[API|Old API documentation]]
+
* [[API|Old API documentation (deprecated)]]
−
*  
+
* [https://openfoodfacts.github.io/openfoodfacts-server/api/ Latest version of the documentation]
−
*
 
  
 
{| class="wikitable sortable"
 
{| class="wikitable sortable"
Line 19: Line 18:
 
|-
 
|-
 
| Dart package || [https://openfoodfacts.github.io/openfoodfacts-dart/ Code Doc] || Example
 
| Dart package || [https://openfoodfacts.github.io/openfoodfacts-dart/ Code Doc] || Example
 +
|-
 +
| Python package || [https://openfoodfacts.github.io/openfoodfacts-python/ Doc] || Example
 +
|-
 +
| Robotoff (Python) || [https://openfoodfacts.github.io/robotoff/ Doc] || Example
 
|-
 
|-
 
| iPhone || [https://github.com/openfoodfacts/openfoodfacts-ios/wiki/ Code Doc] || Example
 
| iPhone || [https://github.com/openfoodfacts/openfoodfacts-ios/wiki/ Code Doc] || Example
Line 38: Line 41:
 
==== Improve the documentation ====
 
==== Improve the documentation ====
 
* Document assumptions and things we (d/w)on't do
 
* Document assumptions and things we (d/w)on't do
 +
== Documentation projects ==
 +
 +
=== Create a developper page for OpenFoodFacts.org ===
 +
 +
Goal: onboard prospective developpers and people wanting to use Open Food Facts in their app
 +
 +
- basic information about getting started as a contributor to the open source 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
 +
source code: https://github.com/openfoodfacts/openfoodfacts-web
 +
 +
=== Build a dedicated documentation site ===
 +
 +
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:
 +
 +
* Read the Docs
 +
* A static site generator such as Hugo, Jekyll, Sphinx, and more
 +
* GitHub Pages
 +
 +
=== Write conceptual overviews of the Open Food Facts products ===
 +
 +
1. Write a conceptual overview and introduction to the Open Food Facts server
 +
- Explain the high level goals, the architecture, the libraries used, the known limitations and the high level wishlist
 +
 +
future url: https://docs.openfoodfacts.org
 +
 +
2. Write a conceptual overview and introduction to Open Food Facts mobile app for iOS
 +
 +
- 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-ios
 +
 +
3. Write a conceptual overview and introduction to Open Food Facts mobile app for Android
 +
- 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
 +
 +
4. Write a conceptual overview and introduction to the Open Food Facts API
 +
- 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
 +
current documentation: https://en.wiki.openfoodfacts.org/
 +
 +
 +
=== Refactor the "How to add a product" documentation ===
 +
 +
* Refresh screenshots and instructions to match the new UI
 +
* Automate screenshot generation across languages
 +
 +
# Create a documentation of the advanced features of Open Food Facts for scientists, journalists…
 +
 +
* Document the advanced search feature, and the graph generation, with examples
 +
 +
=== Document the Open Food Facts API ===
 +
 +
1. General
 +
 +
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.
 +
 +
https://en.wiki.openfoodfacts.org/API
 +
 +
2. 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
 +
 +
3. 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
 +
 +
4. 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 ===
 +
 +
 +
 +
=== Extracting knowledge from Slack channels ===
 +
Some knowledge is stuck in Slack channels. It would be interesting to extract relevant knowledge from them and structure it.
 +
 +
=== Write introduction pages for specific audiences ===
 +
> Users
 +
* Feature page for Web
 +
* Feature page for Android
 +
* Feature page for iOS
 +
 +
> Producer's page
 +
* Startups
 +
* Food companies
 +
* SMB with 300-400 products
 +
* Startup with 12 products
 +
* Global group with processes, different product lines, managed globally
 +
* Hard discounted, no IT
 +
* Food distributors
 +
 +
> Page for journalists with presskits
 +
* Journalists
 +
* Scientific journalist
 +
* Beauty/Healthy/Lifestyle journalist
 +
* Journalist students
 +
* Tech journalists
 +
* Android/iOS/OpenData/Generalists
 +
 +
> Page for developpers
 +
* Developpers
 +
* Indie developpers
 +
* Corporate developpers
 +
 +
> Page for Researchers
 +
* Researchers (AI, Nutrition)
 +
 +
> Page for Politicians/Government
 +
 +
> Page for Dieteticians/Nutritionists
 +
 +
=== Build a directory of Open Food Facts reuses ===
 +
Build a directory of Open Food Facts reuses. It might highlight key features, like displaying the Nutri-Score, contributing back pictures, screenshots, target audiences, countries…
 +
 +
 
[[Category:API]]
 
[[Category:API]]
 
[[Category:Roadmap]]
 
[[Category:Roadmap]]
 +
[[Category:Documentation]]

Latest revision as of 07:25, 7 August 2024

Documentation

Documentation of OFF codebases and APIs
Product Doc Comment
Server code Code doc Example
API API doc Example
Android Code doc Example
Flutter Code doc Example
Dart package Code Doc Example
Python package Doc Example
Robotoff (Python) Doc Example
iPhone Code Doc Example

2021 Documentation roadmap

Project tracking on GitHub

  • Set up a bi-monthly call for documentation

Set up a process to make publication a breeze

  • Publish the new documentation to our new servers
  • Automate the publication of the documentation
  • Deprecate the old wiki doc

Set up a process to keep documentation fresh

  • Keep the documentation on par with the API
  • Generate new separate, fast-moving documentation from the questions in #api or #general, and consider integrating some of it in the main documentation

Improve the documentation

  • Document assumptions and things we (d/w)on't do

Documentation projects

Create a developper page for OpenFoodFacts.org

Goal: onboard prospective developpers and people wanting to use Open Food Facts in their app

- basic information about getting started as a contributor to the open source 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 source code: https://github.com/openfoodfacts/openfoodfacts-web

Build a dedicated documentation site

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:

  • Read the Docs
  • A static site generator such as Hugo, Jekyll, Sphinx, and more
  • GitHub Pages

Write conceptual overviews of the Open Food Facts products

1. Write a conceptual overview and introduction to the Open Food Facts server - Explain the high level goals, the architecture, the libraries used, the known limitations and the high level wishlist

future url: https://docs.openfoodfacts.org

2. Write a conceptual overview and introduction to Open Food Facts mobile app for iOS

- 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-ios

3. Write a conceptual overview and introduction to Open Food Facts mobile app for Android - 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

4. Write a conceptual overview and introduction to the Open Food Facts API - 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 current documentation: https://en.wiki.openfoodfacts.org/


Refactor the "How to add a product" documentation

  • Refresh screenshots and instructions to match the new UI
  • Automate screenshot generation across languages
  1. Create a documentation of the advanced features of Open Food Facts for scientists, journalists…
  • Document the advanced search feature, and the graph generation, with examples

Document the Open Food Facts API

1. General

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.

https://en.wiki.openfoodfacts.org/API

2. 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

3. 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

4. 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

Extracting knowledge from Slack channels

Some knowledge is stuck in Slack channels. It would be interesting to extract relevant knowledge from them and structure it.

Write introduction pages for specific audiences

> Users

  • Feature page for Web
  • Feature page for Android
  • Feature page for iOS

> Producer's page

  • Startups
  • Food companies
  • SMB with 300-400 products
  • Startup with 12 products
  • Global group with processes, different product lines, managed globally
  • Hard discounted, no IT
  • Food distributors

> Page for journalists with presskits

  • Journalists
  • Scientific journalist
  • Beauty/Healthy/Lifestyle journalist
  • Journalist students
  • Tech journalists
  • Android/iOS/OpenData/Generalists

> Page for developpers

  • Developpers
  • Indie developpers
  • Corporate developpers

> Page for Researchers

  • Researchers (AI, Nutrition)

> Page for Politicians/Government

> Page for Dieteticians/Nutritionists

Build a directory of Open Food Facts reuses

Build a directory of Open Food Facts reuses. It might highlight key features, like displaying the Nutri-Score, contributing back pictures, screenshots, target audiences, countries…

Retrieved from "https://wiki.openfoodfacts.org/index.php?title=Documentation&oldid=21888"