Rédiger la doc technique d'une appli

[okoweb]

Bonjour,
J'ai developpé une appli en Php, MySQL, JS, JSON, XHTML et CSS. Le client me demande la documentation technique de cette appli. Je n'ai jamais fait un truc de ce genre. Quelqu'un pourrait me donner les grandes lignes ou bien un modele sur lequel je pourrais m'en inspirer.

Meilleures salutations.

[grunk]

Il faut déjà savoir à qui s'adresse cette documentation. En gros il y'a deux cas :

- Un utilisateur qui te demande une documentation technique :

il voudra en fait un manuel d'utilisateur détaillé. Avec les explications sur toutes les fonctionnalité de l'application. Donc en général on y trouve du texte et tout plein de capture d'écran.

- Un développeur ou personne de l'informatique te demande une doc technique :

On est ici dans le vrai cas (pour moi) de la doc technique. Il voudra sans doute la documentation de ton code (des outils la peuvent la générer , comme phpdoc). Mais aussi des diagramme de conception du genre use case , diagramme de classe , modèle de données , dictionnaire de données ...

Des recherche sur tous ces termes devrait t'aider.

[Benjamin Delespierre]

Hello

Si tu as correctement commenté ton code, tu peux effectivement utiliser phpdoc ou Doxygen:
- http://www.phpdoc.org/
- http://www.stack.nl/~dimitri/doxygen/

Exemple de docu doxygen:

Code :

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
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
<?php
/**
 * PHP AXIOM
 *
 * @license LGPL
 * @author Benjamin DELESPIERRE <benjamin.delespierre@gmail.com>
 * @category libAxiom
 * @package library
 * $Date: 2011-07-27 18:44:09 +0200 (mer., 27 juil. 2011) $
 * $Id: Request.class.php 46 2011-07-27 16:44:09Z TchernoBen@gmail.com $
 */
 
/**
 * Request Class
 *
 * @author Delespierre
 * @version $Rev: 46 $
 * @subpackage Request
 */
class Request {
 
    /**
     * Request paramerers
     * @var array
     */
    protected $_request_parameters;
 
    /**
     * Request parameters filter definition
     * @see http://www.php.net/manual/en/function.filter-var-array.php
     * @var array
     */
    protected $_filter;
 
    /**
     * Browser Capabilities
     * @var array
     */
    protected $_browser_capabilities;
 
    /**
     * Default constructor
     */
    public function __construct () {
        $this->_request_parameters = $_REQUEST;
 
        // TODO Add browser capabilities class
        $this->_browser_capabilities = null;
    }
 
    /**
     * Getter for request vars
     * @param string $key
     * @return mixed
     */
    public function __get ($key) {
        return isset($this->_request_parameters[$key]) ? $this->_request_parameters[$key] : null;
    }
 
    /**
     * Setter for request vars
     * @param string $key
     * @param mixed $value
     * @return void
     */
    public function __set ($key, $value) {
        $this->_request_parameters[$key] = $value;
    }
 
    /**
     * Get the request parameters ($_REQUEST)
     * @return array
     */
    public function getRequestParameters () {
        return $this->_request_parameters;
    }
 
    /**
     * Add many parameters at once.
     * Note: this method is not affected by the filtering,
     * use it carefully if you need to add non-secure data.
     * @param array $collection
     * @return void
     */
    public function addAll ($collection = array(), $method = "merge") {
        if (empty($collection))
            return;
 
        switch (strtolower($method)) {
            default:
            case 'merge':
                $this->_request_parameters = array_merge($this->_request_parameters, (array)$collection);
                break;
 
            case 'add':
                $this->_request_parameters += (array)$collection;
        }
    }
 
    /**
     * Sets an input filter
     * @param array $definition
     * @return boolean
     */
    public function setFilter ($definition) {
        if ($request_parameters = filter_var_array($this->_request_parameters, $definition)) {
            $this->_filter = $definition;
            $this->_request_parameters = $request_parameters;
            return true;
        }
        return false;
    }
 
    /**
     * Get the input filter
     * Wil return null if no filter was set
     * @return array
     */
    public function getFilter () {
        return $this->_filter;
    }
 
    /**
     * Get the browser capabilities
     * @return array
     */
    public function getBrowserCapabilities() {
        return $this->_browser_capabilities;
    }
}

[okoweb]

Envoyé par grunk

- Un développeur ou personne de l'informatique te demande une doc technique :

On est ici dans le vrai cas (pour moi) de la doc technique...

Exact.

Envoyé par grunk

Il voudra sans doute la documentation de ton code (des outils la peuvent la générer , comme phpdoc). Mais aussi des diagramme de conception du genre use case , diagramme de classe , modèle de données , dictionnaire de données ...

Puis-je avoir plus de détails? un modèle ne me fera pas du mal, que je pourrai m'en inspirer.

Merci d'avance...

[Benjamin Delespierre]

Je suis en train d'en rédiger un mais pour l'instant c'est un stub.

Je te le mets en PJ si ça peut t'aider.

[grunk]

Coté diagramme qui peuvent être utile en UML on à :

http://fr.wikipedia.org/wiki/Diagramme_de_classes
http://fr.wikipedia.org/wiki/Diagram...%27utilisation
http://fr.wikipedia.org/wiki/Diagramme_de_s%C3%A9quence

Ce sont les fondamentaux , très faciles à apprendre et maîtriser.

Coté base de données voir principalement :

http://merise.developpez.com/faq/?page=MCD
http://merise.developpez.com/faq/?page=MLD

Dans un monde parfait tous ces diagramme sont normalement fait en phase de conception et éventuellement ajustés pendant le développement. Perso j'ai jamais bossé dans une boite ou on te laisse le temps de faire la conception correctement. On fait donc souvent du retro engineering pour modéliser tout ça

Le PDF fournit par Benjamin est un bon exemple de la partie plus textuel d'une doc technique.