• # La solution ? Payez :>

    Posté par  . Évalué à 7 (+5/-0).

    Si parmi les projets cités, certain ont ou ont eu les moyens d'embaucher des individus, la majorité des projets n'ont pas ce luxe.

    Si la solution à une documentation bancale c'est d'embaucher des rédacteurs, je crains que beaucoup de projets ne puissent se le permettre…

    La majeure partie des morts l'était déjà de son vivant et le jour venu, ils n'ont pas senti la différence.

    • [^] # Re: La solution ? Payez :>

      Posté par  . Évalué à 5 (+3/-0).

      Effectivement, les projets libres qui disposent d'une bonne documentation sont des projets qui paient des gens pour maintenir la documentation (ROOT, Qt. Donc ça semble être nécessaire, mais pas suffisant, car on a aussi des projets libres avec de l'argent et une documentation mauvaise voire inexistante (le noyau linux est donné en exemple).

      Pour KDE, je ne sais pas si les rédacteurs et rédactrices de la documentation sont payés, mais je la juge globalement de bonne qualité (pour l'utilisateur final).

      • [^] # Re: La solution ? Ne lisez pas zdnet

        Posté par  (site web personnel) . Évalué à 4 (+3/-1).

        Car franchement, aucun contenu dans l'article n'étaye l'affirmation du titre selon lequel « la documentation sur les logiciels libres est un véritable capharnaüm ».

        Adhérer à l'April, ça vous tente ?

        • [^] # Re: La solution ? Ne lisez pas zdnet

          Posté par  . Évalué à 4 (+3/-0). Dernière modification le 26 septembre 2024 à 08:46.

          L'article relaie le point de vue de « Jon Corbet, rédacteur en chef de LWN, la meilleure publication sur Linux et superviseur de la documentation du noyau Linux » et de « Alejandro Colomar, qui a maintenu le projet Linux man-pages pendant les quatre dernières années, vient de démissionner. »

          Mais effectivement le titre un peu accrocheur ne rend pas justice à l'état réeel de la documentaion Linux (du noyau) qui s'est bien amélioré ces dernières années, ou des pages de man. Si on ne peut pas vraiment parler de Capharnaûm, les problèmes sont réels : fonctionnalités peu ou mal documentées, difficile à comprendre, etc. Il suffit d'aller visiter les liens présent dans l'article.

          • [^] # Re: La solution ? Ne lisez pas zdnet

            Posté par  (site web personnel) . Évalué à 2 (+0/-0).

            Ça parle peut être de la situation de « Linux » (et de ce coté ci peut être à raison), mais en aucun cas des logiciels libres en général comme l'annonce le titre. Tout au plus il y a des généralisations fumeuses.

            Adhérer à l'April, ça vous tente ?

            • [^] # Re: La solution ? Ne lisez pas zdnet

              Posté par  . Évalué à 1 (+0/-0).

              Nous sommes d'accord. Il ya des projets qui ont une excellente documentation, par exemple Apache, Postfix, Dovecot et d'autre qui sont très mal ou très peu dosumentés.

              L'article tient plus de l'éditorial avec une accroche un peu excessive. Ce n'est pas une raison pour faire une généralisation fumeuse en disant qu'il ne faut pas lire ZDnet (ok, en général c'est pas formidable ;)

              • [^] # Re: La solution ? Ne lisez pas zdnet

                Posté par  (site web personnel) . Évalué à 3 (+1/-0). Dernière modification le 26 septembre 2024 à 10:11.

                Beh je pense qu'on ne peut pas dire en général que la documentation des logiciels libres est un véritable capharnaüm. Par contre on peut dire je pense que ZDnet sort des articles foireux (ou a minima des titres foireux d'article).

                Faut il les lire ou pas ? J'avoue que la proposition « Ne lisez pas zdnet » tient plus de la rhétorique et du sarcasme et ne vise pas réellement à apporter une solution au problème de la qualité journalistique de la presse gratuite en ligne.

                Adhérer à l'April, ça vous tente ?

      • [^] # Re: La solution ? Payez :>

        Posté par  . Évalué à 3 (+1/-0).

        Pour moi le principal problème c'est que beaucoup de développeurs eux-même se foutent royalement de la documentation. Alors oui, écrire un manuel d'utilisation c'est un métier à part entière. Mais entre juste fournir le code et une image docker (ou un snap/appimage/flatpack) et un magnifique manuel utilisateur en 72 langues, je pense qu'il y a un juste milieu.

  • # La documentation est un véritable capharnaüm

    Posté par  . Évalué à 10 (+9/-0).

    Rien à voir avec Linux et les logiciels libres, c'est le même bazar dans le logiciel propriétaire.

    • [^] # Re: La documentation est un véritable capharnaüm

      Posté par  (site web personnel) . Évalué à 8 (+6/-0). Dernière modification le 25 septembre 2024 à 14:32.

      c'est le même bazar dans le logiciel propriétaire

      souvent c'est pire : et vu que ce n'est que parfois que tu as le code source :/

      pas merci aux docs d'install' utiisateur qui n'ont qu'une page d'utile (après avoir enlevé page de garde, page laissée volontairement vide o_O, sommaire, page des spécifications minimales obsolètes, plus les 3 pages de jargon juridique écrit en police 6 illisible…)

    • [^] # Re: La documentation est un véritable capharnaüm

      Posté par  . Évalué à 2 (+2/-2).

      "mais nous sommes toujours dans une situation qui me rappelle beaucoup la chambre de ma fille, où les objets sont jetés n'importe où"

      Histoire de positiver, contrairement à ce que l'on croit, l'ordre ne favorise pas la créativité, c'est même le contraire. Une information ou une documentation "bordélique" peut être l'occasion de faire des découvertes, découvrir des solutions inédites, des domaines qui nous auraient échappé s'ils avaient été rangés au "bon endroit", c'est à dire hors de notre portée puisque ce n'était pas le sujet.
      - Ranger son bureau ou être plus créatif, il faut choisir
      - Créativité : ordre ou désordre, faut-il choisir ?

      • [^] # Re: La documentation est un véritable capharnaüm

        Posté par  . Évalué à 3 (+1/-0).

        Un manque de documentation ou une doc de merde, c'est aussi et surtout des dizaines ou centaines d'heures perdues a debugguer un truc qui ne bug pas vraiment encore qu'on sait pas trop, parce que la doc est le bug.

        Ca, ainsi que la capacité de flinguer tes données "mais t'as qu'a faire des backup!" oui, et si la doc des soft de backup est pourrie?

        Si la doc fait partie des livrables dans le monde pro, c'est pas pour rien. C'est parce que ça permets de ne pas gâcher son énergie a procrastiner, et j'ai encore jamais rien accompli en procrastinant, perso.

        • [^] # Re: La documentation est un véritable capharnaüm

          Posté par  (site web personnel, Mastodon) . Évalué à 3 (+0/-0). Dernière modification le 25 septembre 2024 à 17:04.

          Et, d'expérience, quand la doc utilisateur est bien fichue et bien complète, ça permet aussi de gagner énormément de temps. Déjà parce que les utilisateurs et utilisatrices finaux commencent souvent pas regarder là-dedans. Ensuite parce que ça permet de mieux répondre et plus rapidement aux personnes.

          Et aussi, la rédaction de la doc utilisateur permet de faire de remonter des soucis ergonomiques ou des bugs. C'est ni du temps ni de l'argent perdu.

          Ça n'empêche nullement la créativité parce qu'il y a forcément un moment où il faut faire un truc qui n'est pas exactement prévu. À ce moment là, la question est "comment vais-je faire ça avec les ressources à ma disposition". L'aide permet de débroussailler le terrain.

          « Tak ne veut pas quʼon pense à lui, il veut quʼon pense », Terry Pratchett, Déraillé.

          • [^] # Re: La documentation est un véritable capharnaüm

            Posté par  . Évalué à 6 (+4/-0).

            Déjà parce que les utilisateurs et utilisatrices finaux commencent souvent pas regarder là-dedans.

            Hum … ça j'en mettrai pas ma main à couper. Je dirais que la plupart des gens font comme à la maison : il ne lisent pas le mode d'emploi et vont demander aux autres. En tout cas c'est ce que je constate quotidiennement au travail : bien peu de gens lisent les deux principaux éléments qui permettre de résoudre une grosse partie des problèmes : 1: la documentation (quand elle existe bien sûr) et 2: les logs. Ils préfèrent se perdre en conjonctures farfelues pour dire la fin que ça ne marche pas.

  • # Manuels des distribs commerciales

    Posté par  . Évalué à 5 (+3/-0).

    Il y a les manuels des distributions Linux commerciales :

    C'est bien écrit, il y a beaucoup de contenu.

    Si on est intéressé par un truc en particulier, le chapitre correspondant donne une bonne introduction et donne les références pour aller plus loin (vers la doc en amont, souvent les manpages).

    Le seul bémol est que ça peut être un peu obsolète par rapport aux dernières versions (par exemple en utilisant Fedora ou openSUSE Tumbleweed).

    • [^] # Re: …pas seulement commerciales

      Posté par  . Évalué à 8 (+6/-0).

      Arch n'est pas une distro commerciale, et sa doc est un modèle du genre, même pour les autres distros. Des recherches sur des problématiques debian me renvoient souvent des liens (tout à fait satisfaisants) vers la doc archienne.

      Et il est possible que d'autres distros soient dans ce cas de figure. Donc, comme d'hab, la seule généralité qui soit vraie est que toutes les généralités sont fausses.

      • [^] # Re: …pas seulement commerciales

        Posté par  . Évalué à 3 (+1/-0).

        Mon but n'était pas d'être exhaustif ;-) (ni de faire des généralités).

        Juste donner quelques pistes.

      • [^] # Re: …pas seulement commerciales

        Posté par  . Évalué à 3 (+1/-0).

        J'approuve : j'ai trouvé dans la doc Arch bien plus d'informations pertinentes sur la configuration de NetworkManager par exemple, ou sur systemd, que n'importe ou ailleurs.

      • [^] # Re: …pas seulement commerciales

        Posté par  . Évalué à 3 (+2/-0).

        Le wiki ArchLinux est un des rares cas de documentation collaborative d'ampleur et de très grande qualité (du moins dans la version anglophone, la VF introudit parfois des approximations voire des erreurs). Je suppose que c'est dû à une bonne coordination et modération.

  • # les BSDs...

    Posté par  . Évalué à 5 (+3/-0).

    Ils font ça bien.

    Je me souviens avoir essayé vite fait une openbsd, ou était-ce netbsd? Et… ben c'était pas pareil que debian clairement.

    Sur ces systèmes, on est accueilli par une documentation, qui est en plus claire et intelligible.
    De la a dire que c'est la différence entre le bazaar et la cathédrale, il n'y a qu'un pas, et je le fait.
    C'est pas pour rien qu'en français, un bazar (originellement un marché oriental) est connoté très négativement sur la notion de désordre.
    Difficile d'avoir une doc et une interface cohérentes (ça va ensemble, pour moi) quand chacun fait a sa sauce.

    Il y a aussi le problème que souvent, les projets de logiciel libre ne savent pas ou ils veulent aller, alors, un coup on ajoute une fonctionnalité, le lendemain on la supprime, le surlendemain on la remets mais en différente… évidemment, c'est au travers des années et pas en quelques jours, vous m'aurez compris. (et bien sûr, parfois on retire jamais rien, y compris le code obsolète, et le code deviens une usine a gaz non-maintenable. Ce n'est pas simple, non plus, de choisir quoi ajouter, quoi virer, quoi refondre.)
    Ce point, je l'ai aussi vécu en tant que pro, bien sûr (et la qualité de mon travail diminuait a chaque fois qu'on me demandais de défaire ou refaire un truc, forcément. Ca casse la motivation, ces conneries). Mais je pense que c'est moins visible, quand même, et un chouïa moins pire.

    • [^] # Re: les BSDs...

      Posté par  . Évalué à 4 (+2/-0).

      Comme tu le dis, l'effet "cathédrale" permet d'avoir de la documentation cohérente car les BSD ne sont pas un assemblage d'éléments indépendants, mais un tout cohérent. De plus, j'ai l'impression que sur les divers BSD, le but n'est pas d'avoir la dernière fonctionnalité à la mode ou de suivre la dernière windowserie ou Applerie à la mode, mas d'avoir un système stable et bien documenté, et surtout de ne pas passer son temps à faire, défaire et refaire un truc qui marche déjà. Alors certes on a l'impression qu'ils avancent moins vite que Linux, mais de mon point de vue ce n'est qu'une impression : même s'ils mettent mois de temps à sortir certaines fonctionnalités, ils passent aussi moins de temps à revenir dessus parce qque ça a pas été bien pensé.

    • [^] # Re: les BSDs...

      Posté par  . Évalué à 4 (+2/-0). Dernière modification le 25 septembre 2024 à 20:12.

      souvent, les projets de logiciel libre ne savent pas où ils veulent aller

      Je ne ressens pas cette impression là. Le temps des développeurs n'est pas extensible, ils ont une vie à coté du développement et font avec leurs moyens, y compris concernant la doc qui est très énergivore. Il y a aussi le fait que les projets sont contributifs, que des patches proposés sont intégrés au fur et à mesure, des bugs sont corrigés, cela peut donner une impression d'improvisation mais ce n'est pas le cas puisque les projets avancent. Je vois parfois des "plans de route", exemple:
      https://gitlab.gnome.org/GNOME/gimp/-/milestones

      • [^] # Re: les BSDs...

        Posté par  . Évalué à 2 (+0/-0).

        Attention, je ne dis pas ça pour dire qu'on ne fout rien. Je suis moi-même un contributeur et je sais le temps et l'investissement que certains mettent.
        Je dis juste que, sur les projets auxquels j'ai contribué, j'ai le sentiment, pas forcément partagé, et pas forcément objectif: c'est un sentiment, après tout, qu'il n'y a que rarement de vision long terme.

        Il est clair que la doc et la gestion de projets sont très énergivores et demandent des compétences différentes, en plus. Ajoutes a ça communication aka "marketing", qui est aussi un truc quand même important… des aspects non techniques, non triviaux, et loin d'être gratuits.

        Tu cites gnome, mais soyons honnête, gnome est un gros projet, qu'on aime ou pas. Je ne crois pas que ça soit représentatif de la moyenne. Tout comme parler de "3D experience" dans le logiciel non libre n'est absolument pas représentatif de la moyenne des logiciels non libres.

        Je reconnais que mon phrasé laisse entendre que les choses avancent pas, je me suis mal exprimé, en forcissant trop la caricature.
        Dans le genre projet qui savent ou ils vont, et sont bien plus petit, il y a par exemple i3 qui ont décidé (je sais pas s'ils s'y sont tenus, par contre!) il y a quelques années d'arrêter d'ajouter des fonctionnalités, il est considéré fini, sauf pour les bugfix et la maintenance.
        Ce type de projet est, je pense, et c'est uniquement mon opinion, bien trop rares.

        • [^] # Re: les BSDs...

          Posté par  . Évalué à 3 (+1/-0).

          Tu cites gnome, mais soyons honnête, gnome est un gros projet, qu'on aime ou pas. Je ne crois pas que ça soit représentatif de la moyenne

          Même si Gimp et d'autres programmes en sont dépendants, je ne connais pas vraiment Gnome. Je suis le développement de programmes que j'utilise (principalement versions git) et je constate que leur développement avance de façon cohérente: Enlightenment, Efl, Terminology, XFCE4/devel, Enlightenment16, Gimp, Babl, Gegl, Digikam, Kimageformats, Rawtherapee, Avidemux2, Mpv, Smplayer, Calibre, Transmission, Xapian/Recoll, etc. Dommage que le développement de Xsane soit arrêté (provisoirement?), pour moi, c'est la meilleure interface pour Sane qui existe.
          Concernant la doc pour ces programme, elle existe mais à part pour Gimp ou Rawtherapee ou même Calibre, je ne vois pas ce que peuvent apporter des explications à l'utilisateur. Les pages de man me semblent suffisantes.
          La doc de Gimp pour le développement/debug https://developer.gimp.org/core/

Envoyer un commentaire

Suivre le flux des commentaires

Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.