As an OpenFisca contributor,
I can read about how to use Enum variables,
So that I can use them in my legislation code if I need it

PR Core #604 introduces a Simulation generator. It needs to be documented in the documentation.

In order to increase readability, rename this repo so that its full name is “openfisca/doc” rather than “openfisca/openfisca-doc”.

Related to openfisca/openfisca-france#705.

• Document what is a reform.
• Document the difference between reform and extension.
• Document how to neutralise a variable.
• Document how to rewrite the formula of a variable (“réforme structurelle”).
• Document how to modify a parameter (“réforme paramétrique”).

• Remove references in the doc.
• Ensure there is a ready-to-use binder link with the latest openfisca france available in the doc.
• Warn existing users to save all their data.
• Create a “sunset” page: static page that explains that the service is not offered anymore, and gives a link to the appropriate replacements in the doc. This page should be served on the root subdomain, while existing direct links may still be served.

• Add --python=python2 in https://doc.openfisca.fr/for_users.html
• Document this python version in the user doc.
• Document this python version in the README of core.
• Document this python version in the README of france.
• Document this python version in the README of web-api.
• Unpublish the france source package that looks like it is compatible with all Python versions (see openfisca/openfisca-core#466).

Source: openfisca/openfisca-core#466

EDIT: Replace --python=python2_7 by --python=python2 — the very required version is 2

Currently a formula as the following signature

def formula(person, period, parameters)

What do you think about using people instead of person to reflect the vector computation ?

For instance:

def formula(people, period, parameters)

• Indicate which tools are easy to use/install on a hostile environment
  • Pre-build and make available all the wheels needed by OpenFisca, so that the we can install it without an internet access. The process is already documented, but the wheels are not made availables.

Links to réforme, interface web, API web... cannot be accessed.

The english presentatoin is duplicated. Keep the first paragraph only, followed by a shortcut link to the english section ?

Using linkchecker coupled to Travis?

Since 3 PR now I receive an email from gitbook saying:

We were not able to automatically sync the content of your book openfisca/documentation with the github.com/openfisca/openfisca-gitbook repository.

Go to your book's settings page to resolve this conflict manually.

The solution I found is to create a fake commit like this one.

But this is not scalable.

I do not understand why it happens.

Perhaps it's due to the migration of the gitbook v2 platform. In that case we could delete the book and recreate it, or if it does not work, delete the whole account and recreate it. But that's only a supposition.

As a French-speaking contributor,
I don't have the opportunity to select the French version of the manual,
So that I am deluded into thinking there is one

I had to implement a change in the number of brackets of a taxscale. I did knew it was possible but didn't find the information in the documentation.

It would be useful to document either in the legislation_evolutions or in the detailed parameters documentation.

Pistes de réflexion :

Can FOSS projects benefit from integrating Kanban
Discussion sur le Slack d'Agendashift
Délai de traitement des contributions externes - livre blanc communs

Voici pour moi quelques choses à considérer d’un point de vue « dév » :

• S’il y a de changements que sont introduits comme dépendances d’autres changements, ils peuvent facilement être mis dans de pull requests différentes, en séquence.
• S’il y a de changements avec des dépendances croisées, plusieurs stratégies :
• Créer une PR intermédiaire et faire de petites PR qui n’iront pas sur master mais sur cette PR
• Essayer de couper ces dépendances (là je n’ai pas d’avis car pas encore regardé la PR au plus près) puis faire de PR petites
• Introduire un flag : s’il y a de modifs qui n’ont pas de sens sans l’ensemble, on ajoute les changements et on garde les deux sur une même règle existante, puis on définit un flag, sort de switch, qui dit « pour l’instant, en prod, prend la définition actuelle, et dans les tests, prend les deux ».
• L’unité atomique par excellence d’une PR est le test, donc on pourrait aller même à faire une PR par test, si cela a du sens
• En termes de priorité, c’est mieux traiter les modifications de l’existant avant que les ajouts. Si pour un test en particulier il y a les deux, cela peux aller comme ça : séparer les modifs et les ajouts, et merger avant les ajouts.

On peut, bien évidement, aider à faire quelques pull request d’exemple afin de montrer en concret tout cela, mais il faut qu’on ait une idée de l’interdépendance du saucisson.

Aussi, cela pourrait être intéressant d'envisager une façon d'étendre le circle de contributeurs qui peuvent accepter, voir merger, une pull-request.

Puis, peut-être donner aussi de tips pour faire de rebase du code avant merger.

Et, finalement, de faire un triage par simple, moyen et compliqué des bugs ou de demandes d'amélioration.

Cela dit, ça serait pas mal d’ajouter une liste de tips comme ça quelque part (CONTRIBUTING ou ailleurs).

Related to openfisca/openfisca-core#574

I think the technical documentation about the Web API should not be part of the gitbook documentation.
This would reduce the scope of the gitbook doc to a user guide, not a technical documentation.

Given we launched the reference documentation of the Core recently, we can either:

• move it to the reference documentation (which would contain Core stuff + Web API stuff)
• move it to a Markdown file (endpoints.md?) committed in https://github.com/openfisca/openfisca-web-api

Any thoughts?

Connected to openfisca/openfisca-core#574

The updates don't seem to be always propagated.
#24 and #26 are not deployed, for example.

Follows openfisca/openfisca-france#716

Transfer @fpagnoux explanations to the documentation

Update documentation with Core v20 syntaxes for :

• parameters ; see openfisca/openfisca-core#578
• variables ; see openfisca/openfisca-core#590

Explain:

• how to enable/disable the text trace log
• how to use it to chase bugs

Idea of example to cite: openfisca/openfisca-france#411

• delete test1.py and test2.py in france
• remove references to them in the doc (but keep them inline in blocks)
• move the "getting started" notebook from https://github.com/openfisca/openfisca-web-notebook to https://github.com/openfisca/openfisca-france in a new directory notebooks
• fix the errors notebook(s) (make_reform, etc.)

Follows openfisca/openfisca-france#764

This page is obsolete.

• The python setup.py compile_catalog is outdated as we got rid of i18n.
• python -m openfisca_france.tests.test_basics doesn't work anymore as the tests are no longer packaged within the distribution.

This link http://doc.openfisca.fr/en/openfisca-in-python/reforms.html is broken (in https://github.com/openfisca/openfisca-gitbook/blob/master/fr/contribuer.md )

Reforms are currently presented as part of the “key concepts” while extensions are part of the “contribute” part, and do not link back to reforms.

• Make extensions a part of the “key
  concepts”.
• Make reforms a specific instance of extensions (or the other way around?).
• Make it clear for the user in which case she should use which mechanism.

In order to unify subdomains and repos.

On Extensions page, it should link to https://github.com/openfisca/openfisca-gitbook/blob/master/openfisca-web-api/extensions.md.
@cbenz How do you make this link understandable by gitbook ?

The Test the impact of a reform paragraph is obsolete.

We may want to redesign or remove the whole Getting started section.

Follows openfisca/openfisca-france#716

Cf https://doc.openfisca.fr/openfisca-web-api/install_an_api_instance.html

On https://doc.openfisca.fr

I clicked offline version, PDF, ePub and Mobi and for all of them I received 404 on https://www.gitbook.com

Change Mes_aides_to_openfisca script to take mes_aides situation ID as input

Quand je considère recommander d'OpenFisca,
j'ai besoin de savoir qui sont ses ré-utilisateurs,
pour pouvoir être rassuré·e de bien investir mon capital de réputation.

The logo on the doc main page point to a wrong URL

Foe example it may points to https://github.com/openfisca/openfisca-doc/coding-the-legislation/legislation_parameters.md instead of https://github.com/openfisca/openfisca-doc/tree/master/coding-the-legislation/legislation_parameters.md

This documentation is only available in English, and we don't intend to translate it anytime soon. Even if we were to, it would most probably be as subfolders rather than on fully different domains, to minimise discrepancies, as was the case a few months ago when this doc still had a few (outdated) pages in French.

It should thus be hosted on the openfisca.org domain rather than openfisca.fr.

I currently don't see a major reason for having a subdomain for documentation. Having doc.openfisca.fr is an artefact of hosting being provided by readthedocs.io with a DNS record pointing to their servers. I think we are free to use either a subpath or a subdomain.

Missing any technical reason for choosing one over another, I've asked Twitter 😉

• Update all links in all repos.
• Add a 301 on doc.openfisca.fr

Define JSON situation in documentation input data section. This comes as an addition to scenario format.

In tutorial repository, we use JSON situations with python API but in openfisca-doc, situations are only described as a format to interact with the web API.

https://ui-test.openfisca.fr does not exist anymore. It was a pre-prod version of https://ui.openfisca.fr

Rename https://ui-test.openfisca.fr to https://ui.openfisca.fr everywhere

Several links still point to legislation.openfisca.fr

There are some examples in the documentation that are written for the country-template while other are for openfisca-france.

Imagine the terrified face of users when they see this.

It should be improved :

• Fix variables naming section
• Update "writing YAML tests"
• Reword "The system for France is currently the only one well implemented" in key-concepts/tax_and_benefit_system (it's not super friendly)
• Don't equate two unrelated concepts in key-concepts/variables: "basic income (in France, RSA)"
• Don't mention Paris specifically, use a generic concept like "postal code" in key-concepts/variables
• Use the country template entities as examples rather than France, in key-concepts/person,_entities,_role
• Ditto for roles
• Improve the section title "Application: module used by OpenFisca" in key-concepts/person,_entities,_role
• use country template variables in key-concepts/input_data
• use a country template test case in key-concepts/input_data
• don't recommend using the "modality" of an enum in key-concepts/input_data
• use a country template example in key-concepts/simulation

As a first-time user already convinced of the use of OpenFisca in my context,
I have a bird's eye view of the software components and how to install them,
So that I understand with which piece I should interact

Here

As a new user,
I can find interactive usage examples,
So that I can test OpenFisca and understand what it does

via @monbocal

http://openfisca.org/doc/openfisca-web-api/index.html shows API v18, and swagger https://legislation.openfisca.fr/swagger shows V20.

The doc only briefly mentions how to write scales in parameters files, but not really what they are and how to use them.

Would be nice to document them.

The doc references DatedVariables, which are deprecated. The doc should be adapted.

https://doc.openfisca.fr/coding-the-legislation/40_legislation_evolutions.html#formula-evolving-over-time

Kinta et Christian sont venus aujourd'hui pour installer openfisca et commencer à le prendre en main.

L'installation sur Windows a été douloureuse. openfisca lui-même ça a été, il a juste fallu ajouter python puis pip au PATH. C'est sur paster qu'on a buté : la dépendance sur pastescript n'est pas documentée, et le script start.sh sur smgpa/openfisca ne fonctionnait pas. Axel nous a tiré d'affaires mais c'était non trivial.

Je pense que ça pousse une fois de plus pour qu'on investisse dans un vagrant file.

Une fois qu'on a pu commencer à coder, c'était mieux. On a implémenté progressivement une aide imaginaire avec des critères assez simple. Pour le moment le truc sur lequel on a buté c'est les params.xml: quand tu as trouvé ton paramètre, deviner le path c'est pénible.

Autre point, il faut documenter quelque part :

• Les types de Column disponibles
• Les raccourcis pour les dates

Pendant que Florian expliquait tout ça à Kinta, j'étais moi aussi en train d'implémenter une aide. Je vous ferai un retour bientôt, mais je peux confirmer ma confusion sur ces deux points : SimpleFormulaColumn vs DatedFormulaColumn, et comment faire des opérations sur les dates (period, contrat_travail_debut, contrat_travail_fin).
Pour les dates, une doc de ce genre aurait beaucoup de valeur.

The link at the top of the doc page leading to the pdf file is broken.