Πως διατηρείτε το Documentation στην εργασία σας ειδικά όταν δεν προϋπάρχουν specs;

Let us be honest ο εγγράφως documentation πλέον γίνετε ήρωας της εταιρείας. Συνήθως συνάντησα projects που ΔΕΝ είχαν τεκμηρίωση ούτε και γραπτά specs έτσι σαν λύση όταν συναντώ κάτι στον κώδικα εξάγω τα specs από αυτό και το καταγράφω σε Google Docs, μετά το document αυτό το κάνω share με την ομάδα μου. Αλλά για να ολοκληρωθεί το document αυτό παίρνει χρόνο λόγο και δεν είναι πλήρες αλλά θα έχει κάποια μελανά σημεία λόγο ότι καθοδηγείτε από τα ticket και ποια σημεία βλέπω.

Έτσι θα ήθελα να ρωτήσω εσείς παρόμοιο πρόβλημα πως το λύσατε; Ακόμα πως κάνεις εύκολο indexing και αντιστοίχηση specs <-> αντίστοιχο κομμάτι κώδικα;

9 λεπτά πριν, PC_MAGAS είπε

Let us be honest ο εγγράφως documentation πλέον γίνετε ήρωας της εταιρείας. Συνήθως συνάντησα projects που ΔΕΝ είχαν τεκμηρίωση ούτε και γραπτά specs έτσι σαν λύση όταν συναντώ κάτι στον κώδικα εξάγω τα specs από αυτό και το καταγράφω σε Google Docs, μετά το document αυτό το κάνω share με την ομάδα μου. Αλλά για να ολοκληρωθεί το document αυτό παίρνει χρόνο λόγο και δεν είναι πλήρες αλλά θα έχει κάποια μελανά σημεία λόγο ότι καθοδηγείτε από τα ticket και ποια σημεία βλέπω.

 

Έτσι θα ήθελα να ρωτήσω εσείς παρόμοιο πρόβλημα πως το λύσατε; Ακόμα πως κάνεις εύκολο indexing και αντιστοίχηση specs <-> αντίστοιχο κομμάτι κώδικα;

Εμείς χρησιμοποιούμε twiki μία μορφή wiki , έχουμε search που κάνει αναζήτηση είτε με το όνομα είτε μέσα στο wiki.

Ένα convention είναι να έχεις ίδιο όνομα στο wiki και στην κλάση στον κώδικα , μπορείς να κάνεις Link στο documentation του κώδικα το document των specs.

Μπορείς επίσης να χρησιμοποιείς κάποια standards στις ονοματολογίας όπως

PoSomething για persistent objects

UcSomething για use cases

SfSomething για subflows

AfSomething για alternative flows

DictSomething για dictionary

FtSomething για features

Εμείς με αυτή τη λογική έχουμε στημένο το documentation

Δεν παύει να είναι αρκετά χρονοβόρο στην συντήρηση και να έχεις πάντα στο μυαλό σου να το ενημερώνεις όταν κάνεις αλλαγές στον κώδικα, αλλά έχεις τα πάντα καταγεγραμμένα και γλυτώνεις την γκρίνια α αυτό είναι bug ( όχι λες στον μπιζνεσαιο να οι προδιαγραφές που έκανες accept) και βοηθάει νέο κόσμο που δεν ξέρει καλά την μπίζνα να του απομονώσεις κομμάτια που μπορεί να τα δουλέψει.

Αυτά ως δική μου εμπειρία

Σε κάποια πρότζεκτ έχουμε απλά χρησιμοποιήσει τα tickets στο Jira. Τα γράφει ο ΒΑ και τα εγκρίνει ο PO, και έτσι γίνονται κάτι σαν το contract/specs. Αν χρειαστεί μπαίνουν links σε εξωτερικό documentation (π.χ. για UX designs ή ό,τι άλλο χρειάζεται). Και στα commit βάζουμε τον αριθμό/κωδικό του ticket έτσι ώστε να είναι εύκολο να εντοπίσεις από τον κώδικα τα specs. Δεν είναι τέλειο σύστημα, θέλει μια άλφα πειθαρχία και έλεγχο, και καλό έλεγχο των commit (squash, καλά ονόματα κλπ). Αλλά το έχω δει να δουλεύει αρκετά καλά σε διάφορα και μεγάλα/πολύπλοκα πρότζεκτ.

Μου αρέσει και κάτι που είχε πει ένας συνάδελφος: "documentation is the place where code goes to die" 😁

Προσωπικά απλά κώδικας <--> specs θεωρώ ότι είναι άχρηστος θόρυβος που δεν προσθέτει τίποτα. Jira / azure dev tickets και code review.

Documentation πρέπει να ναι απλά high level, όπως βρίσκεις σε github projects. Δεν χρειάζεται κατι περισσότερο, κι αν προσπαθήσεις σε κατι περισσότερο απλά θα σπαταλάς χρόνο και χρήμα χωρίς να προσκομίσει κανένα ωφελος.