Affichage des résultats du sondage: Que faire lorsque la documentation d’une bibliothèque open source est absente ?

Votants
17. Vous ne pouvez pas participer à ce sondage.
  • S’en détourner. Aucun intérêt s'il n'y a pas de documentation

    12 70,59%
  • Le code source est disponible, c’est largement suffisant

    4 23,53%
  • Soumettre un pull request pour aider à documenter le projet

    4 23,53%
  • Attendre que des contributeurs du projet fassent le boulot

    2 11,76%
  • Autres, précisez dans les commentaires

    1 5,88%
Sondage à choix multiple
+ Répondre à la discussion Actualité déjà publiée
  1. #1
    Chroniqueur Actualités
    Avatar de Patrick Ruiz
    Homme Profil pro
    Rédacteur technique
    Inscrit en
    février 2017
    Messages
    535
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : Cameroun

    Informations professionnelles :
    Activité : Rédacteur technique
    Secteur : Communication - Médias

    Informations forums :
    Inscription : février 2017
    Messages : 535
    Points : 17 926
    Points
    17 926

    Par défaut Open Source : que faire lorsque la documentation d’une bibliothèque est absente ?

    Open Source : que faire lorsque la documentation d’une bibliothèque est absente ?
    Comment gérez-vous des cas de ce type ?

    La documentation constitue une partie importante de l’ingénierie logicielle. En tant que texte écrit, elle permet à la chaîne des intervenants de comprendre comment un soft fonctionne et(ou) comment on doit en faire usage. Seulement, il arrive souvent que cet aspect soit mal mené ou totalement lésé.

    Sur la toile, libui tombe dans cette catégorie de projets ; du moins, pour le moment. Pour le peu qu’on puisse grappiller du dépôt GitHub, il ressort qu’il s’agit d’une bibliothèque portable C dédiée à la conception d’interfaces graphiques. Le projet publié sous licence MIT est compatible avec Windows, Unix, OS X et s’appuie sur les technologies d’interfaces graphiques natives des plateformes mentionnées. Indépendamment du système d’exploitation concerné, Cmake 3.1.0 est le minimum requis pour mener à bien le processus de build. Sous Windows, il est possible d’obtenir la bibliothèque en version statique ou dynamique en faisant usage de Visual Studio 2013. Sur cette même plateforme, MinGW-w64 permet d’obtenir la version statique uniquement.

    Malheureusement, pour aller plus loin dans la connaissance de cette bibliothèque, il faudra posséder l’un des « supers pouvoirs de la taupe », à savoir : sa capacité à fouiner. À ce jour, la documentation du projet est inexistante. Les auteurs du projet ont néanmoins publié des exemples dont celui de l’utilisation de uiTimer (), une fonction introduite à la lib le mois dernier.

    Code cpp : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    #include <string.h>
    #include <stdlib.h>
    #include <time.h>
    #include "../../ui.h"
     
    uiMultilineEntry *e;
     
    int sayTime(void *data)
    {
    	time_t t;
    	char *s;
     
    	t = time(NULL);
    	s = ctime(&t);
     
    	uiMultilineEntryAppend(e, s);
    	return 1;
    }
     
    int onClosing(uiWindow *w, void *data)
    {
    	uiQuit();
    	return 1;
    }
     
    void saySomething(uiButton *b, void *data)
    {
    	uiMultilineEntryAppend(e, "Saying something\n");
    }
     
    int main(void)
    {
    	uiInitOptions o;
    	uiWindow *w;
    	uiBox *b;
    	uiButton *btn;
     
    	memset(&o, 0, sizeof (uiInitOptions));
    	if (uiInit(&o) != NULL)
    		abort();
     
    	w = uiNewWindow("Hello", 320, 240, 0);
    	uiWindowSetMargined(w, 1);
     
    	b = uiNewVerticalBox();
    	uiBoxSetPadded(b, 1);
    	uiWindowSetChild(w, uiControl(b));
     
    	e = uiNewMultilineEntry();
    	uiMultilineEntrySetReadOnly(e, 1);
     
    	btn = uiNewButton("Say Something");
    	uiButtonOnClicked(btn, saySomething, NULL);
    	uiBoxAppend(b, uiControl(btn), 0);
     
    	uiBoxAppend(b, uiControl(e), 1);
     
    	uiTimer(1000, sayTime, NULL);
     
    	uiWindowOnClosing(w, onClosing, NULL);
    	uiControlShow(uiControl(w));
    	uiMain();
    	return 0;
    }

    Ils ont en sus laissé la possibilité additionnelle de consulter le fichier d’en-tête ui.h pour aller plus en avant. D’avis d’observateurs, le projet est prometteur ; de la trempe de wxWidgets. Aussi, comme son illustre prédécesseur, la bibliothèque est dotée de bindings vers une vingtaine d’autres langages dont C++, C#, JavaScript et Python.

    L’équipe du projet a procédé à une extension de la galerie de contrôles offerte par la bibliothèque il y a deux ans. En voici un visuel sous Windows.

    Nom : windows.png
Affichages : 2265
Taille : 49,4 Ko

    Source : GitHub

    Et vous ?

    Avez-vous consulté les ressources disponibles ? Pensez-vous que le projet soit prometteur ? Si oui, pour quelles raisons ?

    Le fait que les sources du projet soient disponibles dédouane-t-il les auteurs de la nécessité de produire la documentation de la bibliothèque (de façon générale) ?

    Pensez-vous qu’il soit logique de soumettre un pull request pour aider à documenter le projet alors que la doc nécessaire pour comprendre le code source est absente ?

    Est-il possible de rédiger efficacement de la documentation pour un projet dont on n’est pas l’auteur ? Si oui, quel pourrait être le temps requis pour cette bibliothèque ?

    Y a-t-il des exemples de projet open source pour lesquels vous avez dû plonger dans le code source pour essayer de rédiger la documentation ? Partagez vos anecdotes

    Voir aussi :

    Que faire pour minimiser l'impact des interruptions sur l'activité de développement de logiciels ? Appliquer les méthodes Agile  ?


    A-t-on besoin d'apprendre la programmation pendant 10 ans avant d'être un développeur accompli ? Partagez votre expérience

    Y a-t-il une corrélation entre diplôme et succès en tant que développeur de logiciels ? Un acteur de la sphère donne son avis

    Comment devenir un meilleur développeur ? La formation et l'expérience sont-elles suffisantes ? Vous êtes invités à partager votre avis
    Contribuez au club : Corrections, suggestions, critiques, ... : Contactez le service news et Rédigez des actualités

  2. #2
    Membre éclairé
    Homme Profil pro
    Ingénieur R&D
    Inscrit en
    mai 2016
    Messages
    198
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Nord (Nord Pas de Calais)

    Informations professionnelles :
    Activité : Ingénieur R&D
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : mai 2016
    Messages : 198
    Points : 705
    Points
    705

    Par défaut

    La réponse dépend de l'usage envisagé.
    Ca parait être un projet en cours de développement, peu mature.
    Pas de doc, spécifications probablement fluctuantes => impossible de baser des développements pérennes là dessus et aucun intérêt en usage professionnel pour l'instant
    A voir dans quelques années, si cette bibliothèque présente un intérêt par rapport à l'existant.
    Pour un usage en loisir ou si on veut participer au projet, les autres réponses sont aussi valables.

  3. #3
    Membre confirmé
    Profil pro
    Inscrit en
    août 2008
    Messages
    190
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : août 2008
    Messages : 190
    Points : 579
    Points
    579

    Par défaut

    Si le projet a déjà des releases, il y a fort à parier que la fiabilité du logiciel laisse à désirer aussi.
    Vaut mieux laisser tomber si on n'a pas de temps à perdre.

  4. #4
    Membre averti

    Homme Profil pro
    Développeur Web
    Inscrit en
    octobre 2007
    Messages
    613
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 37
    Localisation : Belgique

    Informations professionnelles :
    Activité : Développeur Web
    Secteur : High Tech - Multimédia et Internet

    Informations forums :
    Inscription : octobre 2007
    Messages : 613
    Points : 382
    Points
    382

    Par défaut

    Citation Envoyé par captaindidou Voir le message
    Si le projet a déjà des releases, il y a fort à parier que la fiabilité du logiciel laisse à désirer aussi.
    Le manque de documentation n'est pas forcément un reflet de la qualité de la bibliothèque.

    Personnellement, j'ai + de 50 bibliothèques publiées à ce jour... et j'en ai encore plein qui ne sont publiées... mais, pour la plupart, elles ne sont que sommairement documentées, par manque de temps !

    J'adore partager les outils que je crée mais j'ai davantage d'idées que de temps pour les développer et les documenter correctement me prend + de temps que de les coder.

    Comme je m'en sers aussi dans mon travail, lorsque je publie un outil, cela me sert aussi de stockage permanent versionné, auquel je fais appel pour les projets qui en ont besoin.

    Je pense faire du code très intuitif, avec des nommages explicites, dans la majorité des cas, surtout avec un bon IDE, avec un exemple d'usage, cela suffit amplement à qui veut vraiment essayer.

    Après, si j'avais des propositions d'améliorations, même pour la doc, la porte est toujours ouverte.
    Afin d'obtenir plus facilement de l'aide, n'hésitez pas à poster votre code de carte bancaire

    Mon GitHub

Discussions similaires

  1. Le meilleur outil open source pour faire du Flash ?
    Par intik dans le forum EDI/Outils
    Réponses: 7
    Dernier message: 28/01/2010, 09h48
  2. Réponses: 26
    Dernier message: 23/12/2009, 17h33
  3. Que faire lorsqu'une surface est détruite ?
    Par gege2061 dans le forum SDL
    Réponses: 11
    Dernier message: 18/07/2007, 14h27
  4. Que faire lorsque la résolution d'écran est mauvaise ?
    Par gifffftane dans le forum Administration système
    Réponses: 2
    Dernier message: 13/06/2007, 22h30
  5. Que faire lorsque les performances d'une base chute ?
    Par Doctor Z dans le forum Oracle
    Réponses: 11
    Dernier message: 16/02/2005, 14h38

Partager

Partager
  • Envoyer la discussion sur Viadeo
  • Envoyer la discussion sur Twitter
  • Envoyer la discussion sur Google
  • Envoyer la discussion sur Facebook
  • Envoyer la discussion sur Digg
  • Envoyer la discussion sur Delicious
  • Envoyer la discussion sur MySpace
  • Envoyer la discussion sur Yahoo