![[Préc]](http://ptaff.ca/xhtmailimg/prev.png){kind=small}
La (in)sécurité en informatique![[Suiv]](http://ptaff.ca/xhtmailimg/next.png){kind=small}
Percer un trou carré... avec une perceuse?![[Parent]](http://ptaff.ca/xhtmailimg/up.png){kind=small}
2006-11![[Index]](http://ptaff.ca/xhtmailimg/top.png){kind=small}
Index
Salut groupe,
Au boulot, on est en train de regarder comme nous allons faire le gabarit
pour la documentation des projets logiciels sur notre wiki.
Rien de tel que de regarder ce qui a déjà été fait ailleurs pour
s'inspirer. Je me suis souvenu du wiki de amule
(http://www.amule.org/wiki/index.php/Main_Page) qui m'avait jeté à terre à
l'époque (il y a les instructions en espagnol pour installer
le logiciel sur Madrake 10!).
Auriez-vous d'autres exemples, de qualité s'entend, de wiki qui documente
un projet logiciel et dont nous pourrions emprunter l'architecture?
Merci les boyz,
Miguel
Archives de la liste de diffusion ptafflist
Exemple de wiki pour la documentation d'un logiciel
- Exemple de wiki pour la documentation d'un logiciel
Exemple de wiki pour la documentation d'un logiciel
Miguel Tremblay <miguel.tremblay
ptaff.ca>
ptaff.ca>2006-11-29 14:55:55 EST
Re: Exemple de wiki pour la documentation d'un logiciel
Stefan Michalowski <mitchptaff.ca>
ptaff.ca>2006-11-29 15:13:40 EST
Miguel Tremblay wrote:
Si je peux donner un conseil, c'est pratique d'avoir un document maître
qui couvre les points majeurs (description du logiciel, installation,
configuration, utilisation) et ensuite un Wiki avec les FAQ/HOWTO et
autres documents complémentaires.
Ciao,
--
+-------------------------------------------------------+
| |
| Stefan Michalowski, M. Sc. |
| ------------------ |
| Email: illmnecsympatico.ca |
| GPG Key: http://screamerone.zapto.org/k.asc |
| ---------------------------------- |
| "Provider of Open Paradigm Shifts" |
| |
+-------------------------------------------------------+
> Auriez-vous d'autres exemples, de qualité s'entend, de wiki qui
> documente un projet logiciel et dont nous pourrions emprunter
> l'architecture?
Si je peux donner un conseil, c'est pratique d'avoir un document maître
qui couvre les points majeurs (description du logiciel, installation,
configuration, utilisation) et ensuite un Wiki avec les FAQ/HOWTO et
autres documents complémentaires.
Ciao,
--
+-------------------------------------------------------+
| |
| Stefan Michalowski, M. Sc. |
| ------------------ |
| Email: illmnec
sympatico.ca || GPG Key: http://screamerone.zapto.org/k.asc |
| ---------------------------------- |
| "Provider of Open Paradigm Shifts" |
| |
+-------------------------------------------------------+
Re: Exemple de wiki pour la documentation d'un logiciel
> Auriez-vous d'autres exemples, de qualité s'entend, de wiki qui
> documente un projet logiciel et dont nous pourrions emprunter
> l'architecture?
Je ne perçois pas ce que tu trouves de si fantastique sur la page de
documentation de aMule. On y trouve peut-être de tout même un ami;
cependant 207 hyperliens sur une page ne constitue pas ce que j'appelle
un bon design de doc (30 % plus d'hyperliens que sur la page d'accueil
de Yahoo, faut le faire!) et donc pas à mon avis un exemple à suivre.
Cela dit, je pense que la description du problème est prise en mode
« charrue avant les boeufs ».
Utiliser un Wiki vs. un CMS vs. Docbook vs. des pages statiques ne
devrait pas changer à mon humble jugement grand chose sur l'organisation
initiale de la documentation.
S'inspirer de n'importe quelle bonne documentation et la créer en pages
Wiki.
Dépendant du type de projet, le concept « article - discussion » me
séduit généralement (discussion sur la même page que l'article, pas
séparée). Par exemple http://drupal.org/node/52816 ou
http://ca.php.net/strstr
Mais, question fondamentale, quelle genre de documentation doit être
produite? type « décrire un API », « décrire la fonctionnalité et
l'utilisation à des newbies »? « décrire les étapes d'installation à un
sysadmin? » Pas pareil ni dans la forme ni dans le fond.
Wikipedia raconte un peu :
http://en.wikipedia.org/wiki/Software_documentation
--
--====|====--
--------================|================--------
Patrice Levesque
http://ptaff.ca/
wayne
ptaff.ca--------================|================--------
--====|====--
--
- Pièces jointes
Re: Exemple de wiki pour la documentation d'un logiciel
"Yannick Lemieux" <yannick.lemieuxgmail.com>
gmail.com>2006-11-29 16:51:32 EST
Si tu veux un "content management software" je te recommande www.plone.org
Pas joué beaucoup avec, mais ca a l'air prometteur
Pas joué beaucoup avec, mais ca a l'air prometteur
Re: Exemple de wiki pour la documentation d'un logiciel
> Si tu veux un "content management software" je te recommande
> www.plone.org
J'abonde à 100 % dans l'idée du wiki pour de la documentation.
Peut-être mon propos manquait-il de clarté? Je voulais simplement
souligner que la piste de réflexion pour déterminer une structure de
documentation ne dépendait pas à mon avis de savoir si un wiki était
utilisé pour la gestion du contenu.
Et pour tout ce que mon avis vaut, plone ne fait pas partie de mon
top-10 des CMS :)
--
--====|====--
--------================|================--------
Patrice Levesque
http://ptaff.ca/
wayne
ptaff.ca--------================|================--------
--====|====--
--
- Pièces jointes
Re: Exemple de wiki pour la documentation d'un logiciel
"Yannick Lemieux" <yannick.lemieuxgmail.com>
gmail.com>2006-11-29 17:15:29 EST
peux tu m'en recommander un stp?
Je cherche un CMS, toute recommendation serait la bienvenue
Je cherche un CMS, toute recommendation serait la bienvenue
Choix d'un CMS
> peux tu m'en recommander un stp?
> Je cherche un CMS, toute recommendation serait la bienvenue
Deux contraintes : de quoi as-tu besoin, dans quel environnement ça peut
rouler. Est-ce pour rouler sur ta machine locale, pour mettre sur un
serveur? Quel genre de contenu - seulement du texte, ou des images, des
clips audio/vidéo; as-tu besoin d'attacher des fichiers, etc.
En tant que « couteau suisse » du CMS, on peut parler de MediaWiki qui
sans beaucoup de trouble permet à mon avis de couvrir 90 % des besoins
de 90 % des gens.
Comme un CMS donné peut gérer tout et son contraire, peut-être partir de
ceci pour au moins déterminer tes besoins et peut-être en arriver à un
nombre raisonnable de possibilités :
http://www.cmsmatrix.org/matrix/cms-matrix?func=search
--
--====|====--
--------================|================--------
Patrice Levesque
http://ptaff.ca/
wayne
ptaff.ca--------================|================--------
--====|====--
--
- Pièces jointes
Re: Choix d'un CMS
"Yannick Lemieux" <yannick.lemieuxgmail.com>
gmail.com>2006-11-29 19:58:18 EST
Danke Schon!
excellent outil!
excellent outil!
Re: Exemple de wiki pour la documentation d'un logiciel
Miguel Tremblay <miguel.tremblayptaff.ca>
ptaff.ca>2006-11-29 17:31:25 EST
> Je ne perçois pas ce que tu trouves de si fantastique sur la page de
> documentation de aMule. On y trouve peut-être de tout même un ami;
> cependant 207 hyperliens sur une page ne constitue pas ce que j'appelle
> un bon design de doc (30 % plus d'hyperliens que sur la page d'accueil
> de Yahoo, faut le faire!) et donc pas à mon avis un exemple à suivre.
Ce n'est pas que je trouve que l'organisation est bien faite sur ce wiki.
C'est seulement que dans mon historique à moi, c'était la première fois
que je voyais la documentation d'un logiciel sur un wiki. D'où ma forte
impression. Je n'aurais peut-être pas dû mentionner ce fait, désolé.
> S'inspirer de n'importe quelle bonne documentation et la créer en pages
> Wiki.
Je suis d'accord mais je voulais voir s'il y avait moyen d'utiliser de
façon optimale les fonctionnalités d'un wiki pour une documentation. Le
concept de documentation statique peut bien sûr être calqué à l'aide d'un
wiki, y a pas de raisons.
Donc, si vous avez des exemples de documentation logiciel super bien
faite, at large, je suis prenant.
> Mais, question fondamentale, quelle genre de documentation doit être
> produite? type « décrire un API », « décrire la fonctionnalité et
> l'utilisation à des newbies »? « décrire les étapes d'installation à un
> sysadmin? » Pas pareil ni dans la forme ni dans le fond.
Ce n'est pas vraiment pour un logiciel. C'est pour faire le suivie de
projets à être implantés par notre groupe. Il faut donc que la recherche,
le développement et les implémentateurs (c'est mon groupe) puisse
consulter et éditer la documentation de chaque projet.
On veut fournir un gabarit à remplir avant de soumettre un projet pour
implantation. Chaque implantation peut être comparée à un logiciel en
soit. Il y a du code, des responsables, des bug reports, un changelog,
etc.
Je lis ça et je vous reviens là-dessus.
Miguel
Re: Exemple de wiki pour la documentation d'un logiciel
Stefan Michalowski <mitchptaff.ca>
ptaff.ca>2006-11-29 20:22:20 EST
Miguel Tremblay wrote:
Ce que tu sembles vouloir c'est trac (http://trac.edgewall.org/) ou
encore Savane (https://gna.org/projects/savane).
Trac combine un Wiki avec un système de suivis de problème (pense
bugzilla) et s'intègre avec le système de contrôle de version subversion.
Il y a aussi les services web qui habritent les projets libres comme
http://www.sourceforge.net/, https://launchpad.net/,
http://savannah.nongnu.org/ et http://www.berlios.de/ (pas sûr) qui
offrent des services similaires.
Ciao,
--
+-------------------------------------------------------+
| |
| Stefan Michalowski, M. Sc. |
| ------------------ |
| Email: illmnecsympatico.ca |
| GPG Key: http://screamerone.zapto.org/k.asc |
| ---------------------------------- |
| "Provider of Open Paradigm Shifts" |
| |
+-------------------------------------------------------+
> Ce n'est pas vraiment pour un logiciel. C'est pour faire le suivie de
> projets à être implantés par notre groupe. Il faut donc que la
> recherche, le développement et les implémentateurs (c'est mon groupe)
> puisse consulter et éditer la documentation de chaque projet.
>
> On veut fournir un gabarit à remplir avant de soumettre un projet pour
> implantation. Chaque implantation peut être comparée à un logiciel en
> soit. Il y a du code, des responsables, des bug reports, un changelog,
> etc.
Ce que tu sembles vouloir c'est trac (http://trac.edgewall.org/) ou
encore Savane (https://gna.org/projects/savane).
Trac combine un Wiki avec un système de suivis de problème (pense
bugzilla) et s'intègre avec le système de contrôle de version subversion.
Il y a aussi les services web qui habritent les projets libres comme
http://www.sourceforge.net/, https://launchpad.net/,
http://savannah.nongnu.org/ et http://www.berlios.de/ (pas sûr) qui
offrent des services similaires.
Ciao,
--
+-------------------------------------------------------+
| |
| Stefan Michalowski, M. Sc. |
| ------------------ |
| Email: illmnec
sympatico.ca || GPG Key: http://screamerone.zapto.org/k.asc |
| ---------------------------------- |
| "Provider of Open Paradigm Shifts" |
| |
+-------------------------------------------------------+
MediaWiki, tâches, extensions
> > On veut fournir un gabarit à remplir avant de soumettre un projet pour
> > implantation. Chaque implantation peut être comparée à un logiciel en
> > soit. Il y a du code, des responsables, des bug reports, un changelog,
> > etc.
Dans la même veine que les idées de Mitch, j'entends de bonnes choses sur
Request Tracker (de la part de Benoît en tout cas).
http://bestpractical.com/rt
Ton besoin semble hybride (documentation plus suivi), alors ça sent l'heureux
mélange de plusieurs produits. À décider selon le noeud de ton problème (la
doc? la gestion des ressources humaines? les bugs?).
J'ai vu aussi ceci, un plugin pour MediaWiki qui pourrait convenir :
http://meta.wikimedia.org/wiki/Tasks_Extension
En choisissant d'autres extensions, tu pourrais probablement en arriver à faire
un produit hybride pas pire :
http://meta.wikimedia.org/wiki/Category:MediaWiki_extensions
--
--====|====--
--------================|================--------
Patrice Levesque
http://ptaff.ca/
wayne
ptaff.ca--------================|================--------
--====|====--
--
- Pièces jointes
RE: MediaWiki, tâches, extensions
Eric Maziade <mazenovisoft.com>
novisoft.com>2006-11-29 21:19:13 EST
De mon côté, j'utilise mantisbt pour le bugtracking et dokuwiki pour faire
la doc.
Pour la structure de doc, comme il a été mentionné, ça dépend *beaucoup* à
qui la documentation elle adressée.
la doc.
Pour la structure de doc, comme il a été mentionné, ça dépend *beaucoup* à
qui la documentation elle adressée.
Re: Exemple de wiki pour la documentation d'un logiciel
Miguel Tremblay <miguel.tremblayptaff.ca>
ptaff.ca>2006-11-29 20:41:14 EST
> Ce que tu sembles vouloir c'est trac (http://trac.edgewall.org/) ou
> encore Savane (https://gna.org/projects/savane).
Les logiciels pour faire la documentation et gérer le code sont déjà
installés, supportés et opérationnels.
Ce dont j'espère m'inspirer, c'est une documentation bien conçue. Je ne
suis pas à la recherche d'outils.
Merci quand même pour les hyperliens, je les garde en banque.
Miguel
Propulsé par xhtmail