Documentation

[marienfressinaud]

Pour la version 1.0 il faudra avoir :

• de la documentation pour expliquer comment maintenir le code source
• de la documentation pour créer un thème
• de la documentation utilisateur (installation + utilisation)

[Cypouz]

Tout comme pour l'issue #124, j'essaierais de donner un coup de main. En tout cas en terme de documentation utilisateur. Pour le reste, je manque de synapses :)

[marienfressinaud]

Oui, niveau code source, je pense que je vais être obligé de m'y mettre moi-même ^^"
Pour la doc de création d'un nouveau thème, ce n'est pas très compliqué mais il faudra que je le fasse quand même

[Alkarex]

Voir e29be10 (Recherches spéciales intitle: ou inurl: ou author: )

[marienfressinaud]

Sympa :)

J'ai passé la documentation de "peu urgent" à "important", ce sera mieux :) Sinon mercredi je rentre en France, beaucoup de temps dans l'avion, du coup je vais passer une partie de mon temps à réfléchir à la doc et aux fonctionnalités importantes (gestion du multi-utilisateur, gestion des mises à jour, etc.)

[marienfressinaud]

Au passage, ça touche plus ou moins la documentation, mais j'ai commencé à faire mes messages de commit en anglais pour être en accord avec le site / wiki (qu'il va falloir que je continue)

Peut-être faudrait-il traduire aussi les README et CHANGELOG (?)

[Alkarex]

Bonne idée.
Pour le CHANGELOG, on pourrait commencer par écrire les futurs changement en anglais.

[marienfressinaud]

Oui, c'était un peu le sens du point d'interrogation. Le traduire ne servirait pas à grand chose si ce n'est unifier le document

[aledeg]

Sur quelle version de FreshRss base-t-on la documentation?
Si on la base sur la version stable, on risque d'oublier ce qu'on a ajouté comme fonctionnalité.
Si on la base sur la version de développement, on risque de frustrer les utilisateurs qui ne peuvent pas migrer.

Qu'en pensez vous?

[marienfressinaud]

On peut se baser sur la version de développement tout en précisant que ce ne sera dispo que dans la version 0.X (dans un encart ou autre), non ?

[aledeg]

Parfait. C'est ce que je voulais faire.
J'ai commencé la documentation pour le filtrage des articles et je voulais intégrer les nouveautés introduites par @Alkarex sur la recherche par date. Je vais essayer de finir ça ce soir.

[marienfressinaud]

Bonsoir à tous,

voici le tant attendu plan pour la documentation ! Comme cela est déjà fait actuellement, la doc est séparée en doc utilisateurs / doc développeurs. On continue sur cette lancée !

À noter qu'il s'agit encore d'un brouillon qui sera amené à évoluer grâce à vos retours :) Certaines parties ne sont pas forcément encore bien détaillées parce que je n'y ai pas trop réfléchi (puis je suis fatigué). Si j'ai oublié des trucs, si vous pensez que ça s'enchaîne mal, si vous avez pleins d'idées, si c'est trop confus, lâchez vos commentaires !

Restera à écrire ce qui va bien sur le wiki :)

C'est parti !

Documentation utilisateur

1. Page principale
   • FreshRSS = agrégateur de flux RSS trop cool
   • Rapide rappel de ce qu'est un flux RSS (page à part ?)
   • Fonctionnalités phares de FRSS
   • Liens vers les autres points
2. Pour bien commencer
   1. Choisir sa version (master / beta / dev)
   2. Installer FRSS sur son serveur / mutualisé
      • Configuration requise / recommandée
      • Conseils et sécurité
3. Vue principale
   1. Vue normale
      • Fonctionnalités basiques : marquer comme (non) lu / favoris
      • Naviguer dans les articles
      • La barre de menu
      • Voir l'article sur le site d'origine
      • Ordre de lecture
      • Actualiser les flux
   2. Vue globale
      • Prévue pour tout voir d'un coup d'œil
      • Clic ouvre un pop-up pour lire rapidement les articles (même fonctionnalités que la vue normale)
   3. Vue lecture
      • Prévue pour… faciliter la lecture !
      • Plus aucune fonctionnalité sauf navigation (article suivant / précédent) et voir sur site d'origine
   4. Recherche et filtres
4. Gestion des abonnements
   1. Ajouter un flux
   2. Importer et exporter ses flux
      • Basique : fichier OPML
      • Importer ses fichiers Google Reader / FreshRSS (fichiers JSON)
      • Exporter liste OPML / articles favoris / articles des flux
   3. Gestion des catégories (attention, ça va changer… un jour !)
   4. Gestion des flux tronqués
5. Paramétrage
   1. Personnaliser la vue
   2. Options de lecture
   3. Archivage
   4. Raccourcis
   5. Filtres
   6. Authentification
      • Accès anonymes
      • Détails fonctionnalités en fonction de la méthode d'authentification
      • Gestion multi-utilisateurs
      • Configuration aux petits oignons
        • Présentation de différents "workflows"
6. Utiliser une application mobile
   1. Paramétrage de l'API
   2. Liste des applications (EasyRSS, News+)
7. Remonter un problème / une suggestion
   • Tickets Github
   • Comment bien présenter sa demande (notamment donner les logs PHP / FRSS pertinents)

Documentation développeurs

1. Page principale
   • Bienvenue et merci de l'intérêt pour FRSS
   • Différents moyens pour contribuer (testeurs / dev backend / dev frontend / optimisation perf / proposer fonctionnalités / etc.)
   • Liens vers les autres points
2. Par où commencer ?
   1. Configurer son environnement de développement
      • Apache+MySQL = Docker
      • Git et Github
      • Config avec no-cache.txt et la valeur "environment")
   2. Architecture du projet
      • Les grandes parties du code (comment est-il rangé ?)
   3. Coding style
3. Github
   1. Remonter un bug / une suggestion
   2. Système de branches
   3. Proposer un patch
4. Backend
   1. Schéma base de données
   2. Minz
      1. Models
      2. Controllers et actions
      3. Views
      4. Routage (paramètres c et a)
      5. Écriture des URL (Minz_Url::display et raccourci)
      6. Internationalisation (Minz_Translate::t et raccourci)
      7. Comprendre les mécanismes internes
         • FrontController
         • Request
         • Dispatcher
   3. Librairies externes
      • SimplePie and co
   4. Modifier le code
      1. Accès aux informations de la base de données
      2. Écrire une action avec une vue associée
      3. Gestion authentification
      4. Gestion des logs
5. Frontend
   1. Les fichiers de vue
      • Les fichiers .phtml
      • Écrire URLs (_url())
      • Afficher les icônes (_i())
      • Gestion de l'internationalisation (_t())
   2. Design
      • Système fichier template
      • Écrire un nouveau thème
      • Dépôt FreshRSS-base-theme
      • "Surcharger" les icônes (répertoire icons)

[marienfressinaud]

J'ai commencé à mettre à jour la partie de la documentation en français : http://doc.freshrss.org/doku.php?id=fr:start
J'avoue ne pas avoir le courage de m'attaquer à la partie anglaise pour le moment et ça me permet d'aller plus vite comme ça. Y a encore gros à faire :p

J'ai pas mal adapté vis-à-vis de mes propositions d'hier soir : je me suis rendu compte que certaines choses n'étaient pas vraiment pertinentes au moment de l'écrire.

[Alkarex]

👍

[aledeg]

👍

[Alwaysin]

Ze veux collaborer ! Ze veux collaborer ! (oui, je suis là suite à la lecture du billet de blog de @marienfressinaud, j'étais même pas au courant que y'avait une page wiki)
Comment faire pour cela ?

[marienfressinaud]

@Alwaysin > je ne sais pas si j'ai ton adresse mail. Au pire tu m'envoies un mail, je te créé un compte sur http://doc.freshrss.org et tu pourras t'amuser à écrire des nouvelles pages. Le mieux c'est de se baser sur mon post décrivant la structure globale. Il y aura des ajustements à faire, mais globalement c'est ok. N'hésite pas à dire ici ce que tu as modifié (au pire on verra sur le wiki) afin qu'on puisse repasser derrière s'il y a des modifications à faire.

[Alkarex]

Voici une liste de choses à ajouter à la doc : https://github.com/marienfressinaud/FreshRSS/issues?labels=Documentation&state=open

[marienfressinaud]

Deux nouvelles pages écrites ce soir :

• Vos premiers pas qui ne sont que des liens vers des pages qui n'existent pas... pour le moment !
• Remonter un bug, une suggestion, plutôt complète.

[marienfressinaud]

Et j'ai migré les pages du wiki GitHub sur le nouveau, juste du copié-collé. J'en ai profité pour désactiver le wiki GitHub.

[Alwaysin]

@marienfressinaud oui normalement tu l'as, j'avais commencé par t'envoyer des mails avant de me mettre à Github pour faire les suggestions et autres ^^ Mais je t'en renvoie un dans la soirée pour faire le lien avec mon pseudo ici !

[Epy]

Une petite remarque sur le ton de la documentation:
Le "Je" fait bizarre dans une doc, à la limite un "nous" faisant référence à l'équipe des développeurs mais le mieux serait d'avoir un sujet neutre (quand cela est possible) àmha :)

J'attaque doucement ma contribution à la doc, je vais m'ateler aux captures d'écrans pour guider les nouveaux (installation/configuration/utilisation) en me guidant des pages déjà remplies par Marien

[marienfressinaud]

@Epy > oui effectivement, j'ai hésité puis me suis dit que ça me serait certainement remonté si ça faisait trop bizarre ! Je modifierai les quelques occurrences de "je".

[marienfressinaud]

Devant le faible engouement pour l'écriture de la documentation (moi y compris !), je vous propose de nous y prendre autrement. Selon moi, une cause première de démotivation c'est le passage par Dokuwiki (il faut se connecter, l'interface n'est pas top et surtout, la syntaxe me décourage d'avance).

Suivant ce que fait wallabag, j'ai trouvé leur dernière idée très sympa (expliquée ici) : l'idée c'est d'utiliser daux.io (+ sa documentation). On écrit la documentation en Markdown dans un dépôt Git à part entière puis il suffit de lancer un petit script pour transformer le tout en une documentation HTML (plus d'info ici).

Je trouve cette solution vraiment beaucoup plus simple et élégante que Dokuwiki, surtout pour ce qui est des corrections et des suggestions. Bien sûr si l'on part là-dessus je me chargerai de convertir la doc actuelle en Markdown ;)

[aledeg]

https://github.com/titledk/dokuwiki-to-markdown-converter
Ça peut aider :)

[marienfressinaud]

👍

[marienfressinaud]

J'ai commencé une migration, le convertisseur a été bien utile mais évidemment pas suffisant.

• Dépôt de documentation
• Le résultat

[aledeg]

Joli boulot. Le résultat est vraiment pas mal.

[marienfressinaud]

C'est un début, il y a encore pas mal de liens cassés et le formatage n'est pas toujours au top, mais je trouve ça bien mieux qu'avant :) Je voulais modifier légèrement le thème aussi pour ne pas avoir le même que celui de wallabag ^^

[aledeg]

Il y a aussi cet outil http://johnmacfarlane.net/pandoc/
Je ne l'ai pas essayé mais ça à l'air d'être le couteau suisse de la conversion de format.

[marienfressinaud]

J'ai fait quelques modifications ce soir dans la doc v2 et surtout ajouté un fichier README en français pour aider les contributions externes ;)

Je connais Pandoc mais si mes souvenirs sont bons j'avais galéré à l'installer et ce n'est pas forcément pratique à utiliser. Là il suffit d'écrire des fichiers en Markdown et c'est tout, je trouve ça efficace.

[aledeg]

En fait, c'était pour la conversion de dokuwiki vers markdown que je proposais pandoc

[marienfressinaud]

Ok au temps pour moi ! De toutes façons j'ai à peu près fini de tout migrer sur http://doc2.freshrss.org et j'ai ajouté la structure pour la doc développeurs. Y a du boulot mais perso je prends plus de plaisir à écrire la doc maintenant :)

Il faut encore que je trouve une solution pour les images qu'il faut encore migrer mais une fois que ce sera fait je propose de remplacer doc.freshrss.org par la nouvelle version, de fermer ce ticket et de continuer les potentielles discussions dans le dépôt https://github.com/FreshRSS/documentation

[aledeg]

As tu trouvé une solution pour migrer les images? Y-a-t-il une méthode pour ajouter de nouvelles images?

[marienfressinaud]

Je n'ai pas eu le temps de me pencher dessus encore :( Avec le NaNoWriMo et mes activités IRL j'ai du mal à trouver le temps de bosser sur FRSS en ce moment. En fait ils sont prêt à accepter un patch pour définir un répertoire pour les images mais n'ont pas le temps de le faire eux-mêmes (justinwalsh/daux.io#236)

[Epy]

Hello
Désolé pour l'absence alors que je disais être très motivé pour participer :x IRL toussa ..

Je reviens pour y bosser sérieusement ;)

[aledeg]

Dans ce cas, ça se passe ici => https://github.com/FreshRSS/documentation

[marienfressinaud]

Si vous êtes motivés, j'ai mis à jour la procédure pour la doc sur https://github.com/FreshRSS/documentation et http://doc.freshrss.org/ a été mis à jour en conséquent :).

[marienfressinaud]

Et bien il a suffit que je change d'outil pour la doc pour que Daux.io patche enfin mon problème ! Pour référence : justinwalsh/daux.io#236 (comment)