Che cosa costituisce la paternità per la documentazione del software?

Naviga le tue risposte
1

Nella scienza, il contributo intellettuale a un progetto è sufficiente perché qualcuno sia l'autore di un documento. Quando si scrive la documentazione del software, ciò implicherebbe che quasi tutti i soggetti coinvolti nello sviluppo del software saranno inclusi come co-autori.

A differenza della scienza, sembra strano includere i nomi delle persone che non lavorano sul documento. Una ragione è che la documentazione è in continua evoluzione e sono preoccupato di verificare che i coautori esaminino regolarmente lo stato attuale del documento.

domanda: Quando scrivi la documentazione, ci sono delle linee guida per chi, oltre a quelli che contribuiscono direttamente al documento, dovrebbe essere considerato un autore?

chiarimento: sto scrivendo documentazione su come utilizzare un software open source e un database costruito da e per gli scienziati. Poiché questo progetto rappresenta la maggior parte dell'esperienza cumulativa del nostro team con lo sviluppo del software, non abbiamo politiche esistenti per la paternità della documentazione (diversamente da quanto accade con gli articoli di riviste).

    
posta David LeBauer 30.08.2011 - 16:14
fonte

3 risposte

2

Non sono sicuro del tipo di documentazione che stai creando o del tentativo di mantenere la corrente, ma nei miei 20-dispari anni di scrittura tecnica non ho mai avuto il mio nome su un singolo documento che è stato esposto al pubblico. Una delle ragioni è che io sono un appaltatore, e la maggior parte delle aziende non ha il coraggio di ammettere che ci usano tanto quanto loro.

Se è la politica di includere gli autori, ti suggerisco di elencarli per ruolo: autori, contributori (qualcuno che ha scritto meno di un capitolo / sezione), revisori, editori, illustratori e forse anche quelli che ispirano (d ) se ne senti il bisogno.

    
risposta data 30.08.2011 - 22:39
fonte
1

Nella mia esperienza, l'autore o gli autori sono le persone che effettivamente contribuiscono al contenuto principale del documento e producono il lavoro. Altre persone che potrebbero firmare sul documento sono elencate come "revisori". Tipicamente, ci saranno due informazioni associate a ogni nome - il loro ruolo nella produzione del documento (come autore / contributore / originatore o revisore) e il loro ruolo nell'organizzazione (ingegnere del software, project manager, responsabile del software, garanzia della qualità e così via).

Tuttavia, ciò dipende dalle politiche organizzative. La tua squadra o organizzazione dovrebbe decidere chi scrive quali tipi di documenti, chi deve revisionare, come sono documentate quelle recensioni e come catturare qualsiasi tipo di richiesta di approvazione. Questo dovrebbe essere acquisito come parte delle procedure di gestione della configurazione: i documenti devono essere controllati tanto quanto il codice sorgente.

    
risposta data 30.08.2011 - 16:27
fonte
1

A seconda del tipo di documentazione, NESSUN autore deve essere nominato o la società / organizzazione che pubblica il documento è elencata come autore.

Ad esempio,

Sii avvisato: tutti i collegamenti sopra riportati sono in PDF, alcuni dei quali sono piuttosto grandi.

    
risposta data 30.08.2011 - 16:39
fonte

Leggi altre domande sui tag

Qual è la definizione di Time on Task? come impaginare buona documentazione [chiuso]