Quando "dovrebbe" essere usato nella documentazione? [duplicare]

Question

Quando "dovrebbe" essere usato nella documentazione? [duplicare]

#1 da (6 voti)
#2 da (0 voti)
#3 da (0 voti)

5

Stavo leggendo il link e mi sono chiesto alcune domande sullo stile della documentazione. Uno di questi era l'uso della parola "dovrebbe".

Ad esempio:

This method should be overridden when implementing a new Layer class. By default it raises NotImplementedError.

È un posto dove dovrebbe essere usato "dovrebbe"? Mi sembra che quanto segue sarebbe meglio:

This method has to be overridden when implementing a new Layer class. Otherwise, it raises NotImplementedError.

Esiste una guida di stile su tali domande in stile di documentazione indipendente dalla lingua? (ad esempio, se una documentazione dovesse essere scritta in forma passiva o con "tu" o "lo sviluppatore" sarebbe un'altra domanda)

Si noti che non sto scrivendo i requisiti. Questa è una domanda sulla documentazione di una libreria.

documentation

posta Martin Thoma 03.06.2015 - 21:40

fonte

3 risposte

Leggi altre domande sui tag documentation

Qual è un buon linguaggio di script per scrivere attività di amministrazione del server? [chiuso] È possibile commentare uno storyboard?

score 6 · Answer 1

Da quando ho letto RFC 2119 , ho iniziato a fare riferimento ad esso nelle specifiche - anche la documentazione del codice . Un commento come quello che segue nella documentazione aiuta a definire lo standard per l'interpretazione.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (https://www.ietf.org/rfc/rfc2119.txt)

È una RFC piuttosto piccola e facile da capire e basta leggerla una sola volta.

score 0 · Answer 2

Il termine "deve" tende ad essere riservato a situazioni completamente in bianco e nero in cui veramente non ha altra scelta che fare qualcosa in un modo specifico, altrimenti il fallimento è inevitabile.

La persona che scrive la documentazione non può scrivere "deve" se è possibile per qualcuno, in alcune circostanze, non importa quanto sia artificiale, dimostrare che tecnicamente, il problema in discussione non è assolutamente necessario.

In altre parole, suppongo che sia abbastanza facile per qualcuno implementare una nuova "classe layer" senza sovrascrivere il metodo che genera NotImplementedError , e quindi procedere per istanziare quella classe, invocare alcuni dei suoi metodi mentre si effettua sicuro di non invoca il metodo problematico, quindi vai "voilà! Non era necessario sovrascrivere quel metodo dopo tutto!"

Naturalmente, questa intera discussione potrebbe essere un tentativo di leggere troppo nella parola scritta della documentazione. Forse la persona che stava scrivendo la documentazione non era semplicemente incline a usare la parola più precisa possibile della lingua inglese, quindi scrisse semplicemente "dovrebbe" come sinonimo di "must".

score 0 · Answer 3

È stato menzionato RFC2119. Secondo RFC2119, "DOVREBBE" significa: Probabilmente in alcune circostanze potrebbero esserci ragioni per le quali non dovresti seguire il requisito, ma dovresti seriamente pensarci e prendere in considerazione tutte le conseguenze.

Sembra che descriva abbastanza bene la situazione.