Qu’attendez-vous de la documentation d’un navigateur ?

Bonsoir à tous

Je contribue modestement à Otter, un navigateur web dont le développement à commencé après l’abandon d’Opera 12 et bien avant que Vivaldi ne soit annoncé. Malheureusement, l’« équipe » de développement est extrêmement réduite ¹ et le développement avance lentement. Personnellement, ne programmant pas en C++, je me contente de rapporter des bugs, de suggérer de nouvelles fonctionnalités, et plus généralement de prendre part aux discussions sur le dépôt Github.

Le but principal de ce sujet n’est pas de faire la publicité du navigateur. Concrètement, j’ai entrepris il y a quelques mois de documenter le logiciel et de mettre en place un système complet pour gérer la documentation. Après quelques jours de travail régulier, j’ai rapidement été dans l’impossibilité de continuer. Finalement, il m’est apparu que je ne savait pas quoi écrire. La question qui a alors fini par se poser, c’est : quoi documenter ? Otter étant destiné aux utilisateurs avancés (power users) et il faut donc que la documentation aille dans ce sens. Comme je connais trop bien le navigateur, c’est difficile de savoir exactement ce qui est important et ce qui ne l’est pas. C’est pourquoi j’ai décidé de vous demander ce que vous attendez de la documentation d’un navigateur. ZdS est une communauté d’utilisateurs avancés. Admettons que vous souhaitiez passer de votre navigateur actuel à un autre. Que voulez-vous trouver dans la documentation ? Avec vos réponses et vos éventuelles discussions, je crois que je serais en mesure de rédiger une bonne documentation, ou au moins une bonne ébauche le temps que le logiciel se stabilise.

Pour rentrer dans les détails techniques. Le meilleur système de documentation pour notre usage est Sphinx. Il permet de générer une documentation entièrement statique qui peut être intégrée directement dans le navigateur et dans le site web, mais aussi de gérer plusieurs langues facilement. Une fonctionnalités bienvenue est la recherche hors-ligne en Javascript. Vous pourrez retrouver le dépôt Github de la documentation ici : https://github.com/pierreporte/otter-browser-docs. Également, j’ai mis à disposition le rendu HTML : https://pierreporte.github.io/otter-browser-docs. N’hésitez pas à faire des suggestions de ce côté là.

Bonne soirée.

Salut,

Je vois trois sections nécessaires : une très courte introduction comme quickstart, p-ê accompagné d’une vidéo, une section qui rentre plus en détail dans les différences avec les autres navigateurs, et comment faire x chose commune avec Otter et une section qui approfondie chaque paramètre et option possible.

C’est ce que j’attends d’une doc pour un navigateur, même si la troisième, il n’y a presque aucun navigateur qui l’a.

Merci pour ta réponse. Ce que tu proposes était plus ou moins dans mes intentions (y compris l’approfondissement de chaque paramètre et option possibles).

La section quickstart devrait-elle, selon toi (et les autres qui ont plussoyé), être séparée en plusieurs parties dédiées à un navigateur « d’origine » afin de lister les différences ? Mais à quel point peut-on se permettre de présenter ces différences ? Par exemple, je n’imagine pas dire que le bouton de rechargement ne se trouve pas dans la barre d’adresse (comme avec Firefox) mais avec les autres boutons de navigation. C’est un cas facile, mais qu’en est-il des autres ?

Une autre question : préférez-vous vous référer à la documentation intégrée au logiciel (hors ligne), quitte à ce qu’il puisse y avoir quelques erreurs, ou bien à la documentation du site officielle ?

La section quickstart devrait-elle, selon toi (et les autres qui ont plussoyé), être séparée en plusieurs parties dédiées à un navigateur « d’origine » afin de lister les différences ?

Vu la vitesse à laquelle les navigateurs évoluent, il vaut mieux avoir un suivi de malade si on fait ça. Autant je comprends cette démarche dans le cas où il y a peu de logiciels, ou bien quand on se pose en alternative de, autant je ne suis pas convaincu dans le cas des navigateurs.

Une autre question : préférez-vous vous référer à la documentation intégrée au logiciel (hors ligne), quitte à ce qu’il puisse y avoir quelques erreurs, ou bien à la documentation du site officielle ?

Je me réfère à la doc intégré quand elle est facilement disponible, et en ligne sinon (souvent, en pratique). Mais j’apprécie beaucoup la présence d’une doc hors-ligne quand je n’ai pas de connexion.

Que recommanderais-tu alors, pour cette section ?

La partie prise en main rapide est probablement le bout de la doc le plus compliqué à écrire. Je dirais, une description sommaire de l’interface. Où cliquer pour faire des choses de base. Ce qui apparait devant toi étant la meilleure approche pour définir ce qu’est la base, à mon sens.

Un navigateur, c’est plein de boutons. Si tu t’adresses à des gens qui ne connaissent pas forcement bien, dire à quoi ils servent. Et sans les perdre dans une trop longue liste de fonctionnalités. À l’impossible, nul n’est tenu, mais ce serait ce vers quoi il faut tendre.