Cosa includere nella "documentazione tecnica"

Question

Cosa includere nella "documentazione tecnica"

#1 da (7 voti)
#2 da (6 voti)

7

Ho il compito di scrivere la "documentazione tecnica" per un software che stavo sviluppando. Una ragione o l'altra non l'ho mai fatto prima, ho esperienza con SRS, ma questo è qualcosa di diverso. Non sono sicuro che il termine documentazione tecnica sia quello giusto nel caso (il manuale tecnico è migliore?). Questo è ciò che deve essere descritto:

Dove è ospitato
Servizi esterni usati
Lingue e tecnologie utilizzate
Requisiti di sistema e browser supportati

Probabilmente il documento dovrebbe includere un riferimento che ha informazioni sulle credenziali rilevanti. In generale vorrei anche includere una breve informazione sulle tecnologie utilizzate (è un'applicazione web che utilizza react / redux e WebAPI nel back-end).

Questo mi sembra un documento piuttosto standard per me, ma non sono riuscito a trovare qual è il suo nome formale (wrt engineering del software). Apprezzerei se tu condividessi cos'altro potresti includere in questo tipo di documenti? C'è un modello / nome standard per questo?

documentation

posta djvuk 09.08.2017 - 09:59

fonte

2 risposte

Leggi altre domande sui tag documentation

Quali sono le insidie più comuni dello sviluppo del cloud in cui ti sei imbattuto? Perché Facebook nasconde i nomi delle classi CSS?

score 7 · Answer 1

Di solito, la documentazione tecnica è per altri sviluppatori e / o amministratori.

Immaginate:

a) sei un nuovo sviluppatore che si unisce a un progetto software. Che tipo di informazioni sarebbero utili per essere introdotti nel progetto.

b) sei un amministratore che deve mantenere un prodotto software. Che tipo di informazioni sarebbero utili (ad es. In caso di errori, ...).

a)

convenzioni di codifica / denominazione
come eseguire / creare / distribuire l'applicazione
forse una panoramica dell'architettura
il suo posto nel panorama del sistema (che altri sistemi interagiscono con esso)
...

b)

Dove si trova il file di registro
Come configurare l'applicazione
Come riavviarlo / distribuirlo
....

score 6 · Answer 2

Non c'è, ahimè, un insieme di documenti generalmente concordati (e i loro modelli) seguiti da tutte le aziende. Alcuni possono utilizzare una metodologia di gestione del progetto come SSADM, Prince 2, Agile etc, ma anche in questo caso può essere altamente personalizzata per il business.

Quello che stai descrivendo qui è ciò che hai già accennato: è un documento tecnico . Quello che metti qui dipende davvero dal tipo di progetto. Anche se ti disegni un modello specifico, le sezioni variano molto a seconda che tu stia scrivendo un'app per console, un'applicazione web o altro.

Forse prova ad ottenere un timone per vedere cos'altro è già stato scritto e cerca di seguirlo.

Se sei davvero un blazer di strada, devi tenere una mano ferma sul documento in quanto a vari pubblici vorrai aggiungere ogni genere di materiale, quindi devi stare attento che non si trasformi improvvisamente in un documento di formazione o manuale utente ecc.