Domanda:
Come scrivo la documentazione tecnica di consegna prima di lasciare un'azienda?
Akash
2017-10-20 11:08:28 UTC
view on stackexchange narkive permalink

Sto scontando un periodo di preavviso nella mia organizzazione e un project manager mi ha chiesto di scrivere un documento su ciò che ho fatto. Ho accennato brevemente ai punti sui quali ho lavorato, ma non ho fatto alcuna analisi "in-code". Non è soddisfatto del documento, dice

La persona che subentra deve essere in grado di capire cosa è stato fatto da te teoricamente e tecnicamente.

Quale dovrebbe essere il mio approccio nei suoi confronti?

Se avessi iniziato un lavoro e qualcuno ti fornisse un elenco puntato senza conoscere nessuno dei sistemi, l'architettura e l'implementazione, come ti sentiresti?Devi fornire a qualcuno il tipo di informazioni che vorresti vedere se venissi inserito in una nuova organizzazione.Avrai bisogno di approfondire molto oltre alcuni punti elenco.
@JaneS Mi sentirei come una giornata normale in un altro sistema esistente senza documentazione :).Tuttavia penso che il project manager dovrebbe fissare un obiettivo su ciò che dovrebbe essere nella documentazione.OP potrebbe scrivere molto, ma è in periodo di preavviso, in quanto tale è meglio concentrarsi su contenuti eventualmente meno ma più pertinenti e assicurarsi di averli convalidati.
Chiedere come scrivere documentazione tecnica sembra oltre lo scopo di questo sito e questa domanda sembra troppo ampia.Perché non chiedi al tuo Primo Ministro cosa si aspetta?Qual è la cosa peggiore che può succedere?Hai già il periodo di preavviso.
Possibile duplicato di [Il mio datore di lavoro vuole che scriva una guida per svolgere il mio lavoro] (https://workplace.stackexchange.com/questions/33892/my-employer-wants-me-to-write-a-guide-for-facendo il mio lavoro)
@gnat Non è un duplicato.La domanda collegata è chiedere se sono obbligati a scrivere un documento o meno.Questa domanda sta chiedendo * come * scrivere correttamente un documento.
Molto correlato: [Come posso prepararmi per essere investito da un autobus?] (Https://workplace.stackexchange.com/questions/9128/how-can-i-prepare-for-getting-hit-by-a-bus)
Insomma: il meglio che puoi nel tempo a disposizione.Questo è probabilmente iterativo poiché stimare il tempo è complicato.Quindi i proiettili sono un buon inizio ma dovrebbero finire per essere titoli di sezione.E lo sfondo è * sempre * importante, con i nomi delle persone chiave (con rispetto ovviamente)
Perché non fai altre domande e ottieni chiarimenti?Forse hanno un esempio del lavoro di qualcun altro che in precedenza ha lasciato l'azienda.
Qualsiasi documentazione è meglio di niente, ma un lavoro affrettato per documentare qualcosa è solo leggermente meglio di niente.I documenti devono essere scritti durante il lavoro, non l'ultimo giorno.Il tuo manager non ti ha gestito nel miglior modo possibile.
Sei risposte:
user44108
2017-10-20 11:17:20 UTC
view on stackexchange narkive permalink

Stai scrivendo la cosiddetta "documentazione di consegna". Lo scopo di questa documentazione è quello di trasmettere la conoscenza di come funziona questo software e di come è scritto, mantenuto e distribuito alle persone che ti seguiranno.

C'è una domanda / risposta correlata su Stack Overflow che generalmente copre gli argomenti che devi affrontare nel tuo documento:

Quali sono gli elementi fondamentali da includere nella documentazione di supporto?

Citato in parte:

• La documentazione del codice (javadoc, doxygen, ecc.)
• Dettagli sul processo di compilazione
• Dove ottenere il sorgente corrente
• Come segnalare bug ( accadranno)
• Instradamento per fornire patch alla fonte o ai clienti

• Come funziona (semplice, ma spesso trascurato)
• Parti personalizzabili dall'utente (ad es. è un componente di scripting)
• Contatti primari per ogni componente, noto anche come percorso di escalation
• Incoraggiamento per il feedback dal supporto su cos'altro vogliono vedere

Considera anche :

  • Credenziali di sistema / utente richieste (don ' t mettere le password nella documentazione!)
  • Dove si trovano dev / test / UAT / database / qualsiasi altro server associato
  • Dove si trova il server di produzione
  • Passaggi di distribuzione
  • Indipendentemente dal fatto che siano coinvolte licenze
  • Posizione dei requisiti originali / documenti di analisi per ciascuna parte di lavoro

Google "Documentazione di consegna" lo farà ti darò anche più approfondimenti.

Per risparmiare tempo, scriverei una serie di punti elenco (come sopra e dalla tua ricerca secondo questo progetto) e li presenterei al tuo PM. Chiedigli di spuntare quelle che vuole vedere e di aggiungere quelle che ritiene appropriate.

Far sì che il Primo Ministro rispetti ciò che vuole è un ottimo ideale.Anche se corri il rischio che ti dica "Tutto! Ieri!"MrGreen
Ciò può dipendere da vincoli di tempo;alcune cose potrebbero essere più importanti di altre.Potrebbe esserci già della documentazione per coprire anche alcuni di questi titoli.
Nonostante quello che potrebbe pensare il manager, di solito il primo punto (documentazione del codice) è di gran lunga il meno importante.Quando hai bisogno della fonte, non puoi indovinare dove trovarla o quale prendere.O lo sai o non lo sai.Anche le build a volte sono estremamente complicate.Il codice (se non è terribile) dovrebbe essere comunque leggibile.
Essendo io stesso PM, il 90% delle cose che hai elencato mi aspetto che siano già state scritte da me stesso come PM.
TripeHound
2017-10-20 14:24:20 UTC
view on stackexchange narkive permalink

Adotterò una visione un po 'cinica, da avvocato del diavolo ...

La risposta di Snow elenca un sacco di cose buone che dovrebbero essere documentate, ma quasi tutte di questo dovrebbe già essere documentato e continuamente aggiornato. Se questa documentazione non esiste (e so che ci saranno molti posti in cui non esiste), allora è essenzialmente un fallimento della tua gestione non mettere in atto le giuste pratiche durante il tuo tempo con l'azienda. In tal caso, cercare di rimediare al loro fallimento "scaricando" sulla persona che si lascia la responsabilità di "documentare tutto" non va bene.

La risposta di Kilisi suggerisce " Fallo come vorresti leggerlo se dovessi subentrare ", che è di nuovo un bell'ideale, ma forse dovrebbe essere temperato tenendo conto di ciò che ti è stato dato il primo giorno. Se ti è stato dato quasi nulla, ad esempio: " c'è il codice, se non riesci a capire come funziona qualcosa, chiedi a qualcuno " e la situazione non è cambiata da quando hai ricominciato, ancora una volta, non è veramente responsabilità della persona che se ne va per correggere le cattive pratiche.

Il succo di ciò che sto cercando di dire è: se si applica, non farti intimorire cercando di correggere pratiche intrinsecamente cattive .

  • Se la maggior parte delle cose sono già documentate in dettaglio, il tuo "passaggio di consegne" dovrebbe essere relativamente breve; la manciata di cose "nella tua testa" di cui gli altri potrebbero non essere pienamente consapevoli. Saprai meglio di cosa si tratta, ma dovresti chiedere consiglio al tuo project manager su qualsiasi area specifica a cui è interessato.

  • Se la documentazione esistente è scarsa, non aggiornata o inesistente, non è tua responsabilità correggere il "fallimento sistemico" mentre esci. Scarica il cervello quanto puoi, per aiutare il povero stronzo che ti sostituisce, ma non sentirti in colpa perché questa situazione avrebbe dovuto essere affrontata (dalla direzione) molto tempo fa.

Ovviamente, se hai deliberatamente "accumulato" informazioni che solo tu conosci e non hai tenuto aggiornata la documentazione esistente, dovrebbe essere tua responsabilità riuscire finalmente a passare quelle informazioni nel modo più utile possibile!

Sono d'accordo che non è pratico risolverlo il tuo ultimo giorno, ma * fortemente * non sono d'accordo sul fatto che spettava alla "gestione" ottenere la documentazione messa a punto durante il tuo tempo in azienda.** È tua * responsabilità * personale * ** documentare i dati cruciali riguardanti il tuo lavoro durante il lavoro, indipendentemente dal fatto che la direzione lo dica o meno, proprio come è tua responsabilità personale fare un buon lavoro in primo luogo.È una questione di etica, non di morale.
@Wildcard.È una responsabilità comune.Sì, un programmatore dovrebbe documentare tutto, ma sappiamo anche che molti di loro preferirebbero andare avanti con il prossimo pezzo di lavoro "reale".La direzione può aiutare rendendo il processo il più indolore possibile, incoraggiando una cultura che lo desidera e applicandolo dove necessario.
@TripeHound ... per non parlare del fatto che la documentazione è la prima cosa da fare ogni volta che le cose si fanno difficili.Quando c'è la possibilità di scegliere tra rispettare la scadenza o rimanere nel budget e ottenere la documentazione, la documentazione cade ogni volta nel dimenticatoio, e di solito è nelle direttive del management, non perché è così che le risorse tecniche lo vogliono.
@HopelessN00b True.E il fulcro della mia risposta è _se_, per qualsiasi motivo, di chi fosse la "colpa", un'azienda si trova "sottodocumentata", aspettarsi che qualcuno che lasci magicamente "aggiustare" le cose non è ragionevole.Altre risposte spiegano molto bene cosa fare se tutto è come dovrebbe essere.
@TripeHound siamo in completo accordo.
compra "dumping" -> con "dumping"
Kilisi
2017-10-20 12:13:22 UTC
view on stackexchange narkive permalink

Quale dovrebbe essere il mio approccio nei suoi confronti?

Fallo come vorresti leggerlo se fossi tu a subentrare. A parte questo, comunica il tuo avviso e concentrati su dove sta andando la tua carriera. A meno che il tuo capo non ti dia un formato da seguire, non c'è molto altro che puoi fare di cui sarà completamente soddisfatto.

Di solito eseguo una procedura dettagliata di tutti i miei compiti assumendo deve essere seguito da un principiante. Quindi niente abbreviazioni, niente slang ecc.

Tom
2017-10-20 14:25:59 UTC
view on stackexchange narkive permalink

La cosa più importante che vorrei sapere quando prendo il posto di un altro sviluppatore è il comune "cosa, perché, come" del progetto. Ovvero:

  • Che cos'è? Che cosa fa?

  • Perché hai scelto di fare le cose in un certo modo? Mi chiederò sempre perché uno sviluppatore abbia deciso di adottare un determinato framework o linguaggio e contesto o avvertire su certe cose che non avevo considerato essere inestimabili.

  • In che modo il progetto risolve il problema problemi elencati?

L'altra cosa più importante, è procurarsi una macchina nuova, niente a che fare con il progetto e provare ad arrivare a una configurazione funzionante su di essa (proprio come loro dovrò farlo quando subentreranno).

Non hai idea di quante volte ho chiesto a un ex sviluppatore del progetto perché la loro documentazione non funzionava e loro mi hanno detto "Oooh , sì, devi solo aggiungere questa variabile d'ambiente, l'avevo dimenticato. " È normale e umano non annotare ogni passaggio di un'installazione, ma renderà la vita molto più facile al prossimo sviluppatore dato che ora sei nella giusta mentalità.

hamstercat
2017-10-20 18:10:32 UTC
view on stackexchange narkive permalink

Immagina di fare un trasferimento di conoscenze con un altro sviluppatore che riprenderà da dove avevi lasciato. Normalmente, esamineresti il ​​codice ad alto livello e menzioneresti qualsiasi cosa di interesse, particolari punti deboli, luoghi che spesso hanno bug, ecc. Questo ti darà i punti di partenza per creare la documentazione.

Poiché si tratta di un documento scritto e il prossimo dipendente non sarà in grado di porre domande, potresti voler essere più esplicito di quanto non faresti con una panoramica verbale.

Viktor Mellgren
2017-10-20 14:24:28 UTC
view on stackexchange narkive permalink

La persona che assume i tuoi compiti sta già lavorando per l'azienda o avrà qualche sovrapposizione con te?

Se è così, lascia che quella persona riveda la documentazione se è abbastanza buona per lui / lei. (O se hai un collega che può aiutarti.) È impossibile coprire tutto, quindi concentrati sulle cose difficili, sulle cose strane, sulle eccezioni agli standard del settore e così via.

E lo so è noioso e probabilmente mentalmente hai già lasciato l'azienda. E a seconda del motivo per cui hai lasciato più o meno fedeltà all'azienda. Ma suggerisco di lavorare in modo iterativo in modo da avere obiettivi più brevi e richiedere spesso feedback. Poiché hai poco tempo a disposizione e l'azienda dovrebbe utilizzarti nel modo più efficiente possibile, scrivere documentazione non necessaria è uno spreco e potrebbero perdere le cose importanti.



Questa domanda e risposta è stata tradotta automaticamente dalla lingua inglese. Il contenuto originale è disponibile su stackexchange, che ringraziamo per la licenza cc by-sa 3.0 con cui è distribuito.
Loading...