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

L'auteur de ce sujet a trouvé une solution à son problème.
Auteur du sujet

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


  1. Le développeur original est presque seul bien que deux autres contributeurs participent régulièrement. 

Édité par TD

« LaTeX is to a book what a set of blueprints is to a building » (Paul Dulaney) | Mon planétaire

+0 -0

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. :-°

Édité par tleb

Auteur du sujet

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 ?

« LaTeX is to a book what a set of blueprints is to a building » (Paul Dulaney) | Mon planétaire

+0 -0

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. :-°

Hier, dans le parc, j’ai vu une petite vieille entourée de dinosaures aviens. Je donne pas cher de sa peau.

+0 -0
Auteur du sujet

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.

Gabbro

Que recommanderais-tu alors, pour cette section ?

« LaTeX is to a book what a set of blueprints is to a building » (Paul Dulaney) | Mon planétaire

+0 -0

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

Hier, dans le parc, j’ai vu une petite vieille entourée de dinosaures aviens. Je donne pas cher de sa peau.

+0 -0
Vous devez être connecté pour pouvoir poster un message.
Connexion

Pas encore inscrit ?

Créez un compte en une minute pour profiter pleinement de toutes les fonctionnalités de Zeste de Savoir. Ici, tout est gratuit et sans publicité.
Créer un compte