Πώς να γράψετε τεχνικές προδιαγραφές που πραγματικά πλοία

Εάν διαβάζετε αυτό, οι πιθανότητες είναι ότι έχετε κοιτάξει σε μια ημιτελή τεχνική προδιαγραφή στις 2 π.μ., προσπαθώντας απεγνωσμένα να το τυλίξετε πριν από την αναχώρηση. Αλλά εδώ είναι το πράγμα: όταν γίνονται καλά, οι τεχνικές προδιαγραφές δεν είναι καθήκοντα από την τεχνολογία σας. είναι ένα από τα πιο ισχυρά εργαλεία που χρειάζεστε για να οδηγήσετε τα χαρακτηριστικά από την ιδέα στην παραγωγή. θα σας δείξω πώς προσεγγίζω τη συγγραφή τους, με βάση την εμπειρία μου στο Monzo και τα μαθήματα που έχω πάρει από τους μηχανικούς στο AWS, το Google και το Meta. Το υπόβαθρό μου είναι η μηχανική λογισμικού, αλλά πολλά από αυτά μεταφέρονται σε άλλους τεχνικούς κλάδους. Why write tech specs anyway? Γράφοντας τεκμηρίωση αισθάνεται σαν λεωφορείο όταν θα μπορούσατε να στείλετε κώδικα. αλλά μείνετε μαζί μου εδώ, επειδή μια καλή τεχνική προδιαγραφή κάνει πολύ περισσότερο από την ικανοποίηση ορισμένων απαιτήσεων διαδικασίας. Όταν χρησιμοποιείται σωστά, οι τεχνικές προδιαγραφές σας βοηθούν: Επιβεβαιώστε την ιδέα πριν σπαταλήσετε εβδομάδες κατασκευής - έχω σκοτώσει περισσότερες κακές ιδέες κατά τη διάρκεια της φάσης spec από ό, τι με νοιάζει να παραδεχτώ. Πάρτε buy-in από τους ανθρώπους που πραγματικά έχουν σημασία - το προσωπικό σας μηχανικός, ο διαχειριστής του προϊόντος σας, ο κύριος μηχανικός που έχει δει τα πάντα. Επαναλάβετε το σχέδιο υψηλού επιπέδου με πιο έξυπνους ανθρώπους από εσάς - δεν είμαι ο πιο έξυπνος άνθρωπος στο δωμάτιο, και αν είστε ειλικρινείς με τον εαυτό σας, δεν είστε ούτε εσείς. Μοιραστείτε τις γνώσεις σας με την ομάδα σας - Η εγγραφή νέων μηχανικών γίνεται "διαβάστε αυτή την προδιαγραφή" αντί για "αφήστε με να εξηγήσω αυτή την αρχιτεκτονική για τρίτη φορά αυτή την εβδομάδα". Μοιραστείτε τις γνώσεις σας με τους ενδιαφερόμενους εκτός της μηχανικής - Ο διαχειριστής προϊόντων, η ομάδα συμμόρφωσης ή οι άνθρωποι των χρηματοοικονομικών πρέπει να κατανοήσουν τι χτίζετε και γιατί. Χρησιμοποιήστε ως επικύρωση όταν ολοκληρωθεί η εργασία - Έχετε πραγματικά λύσει αυτό που θέλατε να λύσετε; Η προδιαγραφή είναι η κάρτα βαθμολογίας σας. Spec-driven ανάπτυξη και LLMs LLMs έχουν αλλάξει τον τρόπο που σκέφτομαι για τις τεχνικές προδιαγραφές. Τα LLMs λειτουργούν καλύτερα με αυστηρές τεχνικές προδιαγραφές. Όσο λιγότερο αφήνετε στη φαντασία, τόσο καλύτερα. Μια καλά καθορισμένη προδιαγραφή μπορεί να τροφοδοτηθεί σε ένα LLM για αυτόματη δημιουργία εισιτηρίων ή ακόμη και τεχνική εφαρμογή. Μπορείτε να δημιουργήσετε δοκιμές από τις προδιαγραφές σας. Μπορείτε να χρησιμοποιήσετε τα LLMs για να σκεφτείτε σε μέρη της πρότασής σας, να τους ζητήσετε να κάνουν έρευνα ή ακόμα και να βοηθήσουν στον εντοπισμό ελαττωμάτων στη λογική σας. Έχω ένα άλλο άρθρο που έρχεται τις επόμενες εβδομάδες αφιερωμένο στην ανάπτυξη με ειδικότητες με LLMs. Κρατήστε ένα μάτι γι 'αυτό - έχω πειραματιστεί με αυτό σε κλίμακα και τα αποτελέσματα είναι πραγματικά εντυπωσιακά. Αλλά ακόμα και αν δεν αγγίξετε ποτέ ένα LLM, η πειθαρχία της γραφής μιας αυστηρής προδιαγραφής πληρώνει μερίσματα. Ανατομία μιας καλής τεχνικής πρότασης (μέρος 1) Μια καλή τεχνική προδιαγραφή είναι καλά δομημένη, εύκολη στην κατανόηση και λειτουργική. Θα πρέπει να είναι εύχρηστη για τα στελέχη και αρκετά λεπτομερής για τον μηχανικό που την εφαρμόζει. Εδώ είναι το πρώτο μισό της ανατομίας. Αυτό είναι αυτό που γράφετε πριν πάρετε buy-in. Τι προσπαθείτε να λύσετε; Ξεκινήστε με τη δήλωση του προβλήματος. όχι η λύση - το πρόβλημα. έχω δει τόσες πολλές προδιαγραφές που πηδούν κατευθείαν σε Χωρίς ποτέ να εξηγήσει τι έχει σπάσει. «Πρέπει να χτίσουμε μια μικροεπιχείρηση με το GraphQL» Στο startup μου, το Tandem, έχω ένα απλό τεστ: θα μπορούσε ο Jack, ο μη τεχνικός συνιδρυτής μου, να κατανοήσει το πρόβλημα, απλά διαβάζοντάς το; Αν όχι, ξαναγράψτε το. Μερικές τεχνικές που λειτουργούν: Χρησιμοποιήστε συγκεκριμένα παραδείγματα: Όχι "οι χρήστες βιώνουν καθυστέρηση" αλλά "οι χρήστες περιμένουν κατά μέσο όρο 8 δευτερόλεπτα για να φορτώσουν το ιστορικό συναλλαγών τους και βλέπουμε 23% πτώση σε αυτή την οθόνη". Δείξτε τον επιχειρηματικό αντίκτυπο: «Αυτό μας κοστίζει περίπου £2.3M ετησίως σε χαμένες μετατροπές» είναι πολύ πιο πειστικό από το «αυτό είναι αργό». Συμπεριλάβετε αποσπάσματα ή δεδομένα: Εάν έχετε έρευνες χρηστών, καταγγελίες πελατών ή δεδομένα παρακολούθησης, ρίξτε το. Τι δεν προσπαθείς να λύσεις; Το scope creep είναι πραγματικό, και αν δεν καλέσετε ρητά έξω από το πεδίο εφαρμογής, θα περάσετε τον επόμενο μήνα συζητώντας για περιπτώσεις άκρων που δεν έχουν σημασία. Φανταστείτε αυτό: παίρνετε μια πρόταση από την ομάδα της πλατφόρμας για να αναβαθμίσετε στη λαμπερή νέα βιβλιοθήκη κοινής χρήσης τους. Φαίνεται απλό, σωστά; Απλά ανταλλάξτε μερικές εισαγωγές, ενημερώστε μερικά εξαρτήματα. Αλλά στη συνέχεια ανακαλύπτετε ότι η νέα βιβλιοθήκη χρησιμοποιεί ένα εντελώς διαφορετικό σύστημα δρομολόγησης κάτω από αυτό. Τώρα πρέπει να επαναπροσδιορίσετε κάθε διαδρομή στην εφαρμογή σας. Τότε συνειδητοποιείτε ότι τα πρότυπα πλοήγησης της ομάδας προϊόντων σας δεν ταιριάζουν απόλυτα στο νέο μοντέλο, οπότε χρειάζεστε προσαρμοσμένα περιέλιγμα. Η ομάδα προϊόντων που εξαρτάται από αυτή τη κοινόχρηστη βιβλιοθήκη; Όλοι μπλοκάρουν τις ίδιες αλλαγές. Μόλις μετατράπηκε σε μια προσπάθεια μετανάστευσης έξι μηνών που κρατάει το έργο χαρακτηριστικών σε ολόκληρο τον οργανισμό. Άλλο «Επικαιροποίηση απλής χρήσης» An explicit Αυτό το τμήμα θα μπορούσε να το πιάσει νωρίς. Σου δίνει την άδεια να πεις όχι. Και προστατεύει το χρονοδιάγραμμα σας από αυτές τις φαινομενικά αθώες προτάσεις που μπαλόνια σε οργανωτικούς εφιάλτες. «Τι δεν λύνουμε» "why-notism" Γιατί πρέπει να λυθεί αυτό το πρόβλημα; Δεν χρειάζονται όλα τα προβλήματα να λυθούν. Μερικά μπορούν να ζήσουν με προβλήματα. Μερικά δεν είναι στην πραγματικότητα προβλήματα, μόνο μικρές δυσκολίες. Γιατί πρέπει αυτός να πάρει την προσοχή και τον χρόνο μηχανικής; Make the case clearly: ΕΠΙΠΤΩΣΗ ΣΤΟΥΣ ΧΡΗΣΤΕΣ: Πόσους ανθρώπους επηρεάζει; Πόσο άσχημα; Επιπτώσεις στην επιχείρηση: έσοδα, διατήρηση, μετατροπή, λειτουργικά έξοδα; Επιπτώσεις στη μηχανική: Είναι αυτό το χρέος της τεχνολογίας που επιβραδύνει κάθε άλλο έργο; Επιπτώσεις στη συμμόρφωση ή τον κίνδυνο: Θα εκραγεί αυτό σε έξι μήνες αν δεν το διορθώσουμε; Είμαι ένας μεγάλος πιστός στην επίδειξη του έργου σας εδώ. μην πείτε μόνο Κάποτε βασίσαμε μια πρόταση για την αλλαγή του κειμένου σε ένα κουμπί σε ένα πείραμα που απέδειξε μια αύξηση 23% στη μετατροπή, η οποία μεταφράστηκε σε +£12k ARR. "this is important." "Αυτό το αντίγραφο του κουμπιού θα μπορούσε να είναι καλύτερο." Γιατί τώρα; Το χρονοδιάγραμμα έχει μεγαλύτερη σημασία από ό, τι νομίζουν οι άνθρωποι.Έχω δει τέλεια καλές προτάσεις να καταρρέουν επειδή δεν ήταν η κατάλληλη στιγμή.Και έχω δει μετριόφθαλμες προτάσεις να λάμπουν επειδή το χρονοδιάγραμμα ήταν τέλειο. Why is now the best time to solve this problem? Think about: Εξωτερικές προθεσμίες: ρυθμιστικές αλλαγές, εκστρατείες μάρκετινγκ, επίδειξη συνεδρίων Εσωτερική ετοιμότητα: Έχετε τη σωστή υποδομή στη θέση σας; Η σωστή ικανότητα της ομάδας; : Are there other projects that need to ship first? Dependencies : Sometimes, there's a narrow window when solving something is easier than it'll ever be again. Opportunity windows Εδώ είναι ένα συγκεκριμένο παράδειγμα. Είχαμε μια πρόταση να χρησιμοποιήσουμε τοπικές ζώνες ώρας στις καταστάσεις τραπεζικών λογαριασμών αντί για UTC. Ο χρόνος ήταν κρίσιμος - θέλαμε να το κάνουμε αμέσως μετά την εξοικονόμηση φως της ημέρας στο Ηνωμένο Βασίλειο. Αυτό μας έδωσε έξι μήνες όταν η UTC και η τοπική ώρα ήταν η ίδια. Έπρεπε επίσης να διατηρήσουμε τις ιστορικές καταστάσεις στην αρχική ζώνη ώρας για νομικούς λόγους. Ξεκινώντας αμέσως μετά την αλλαγή των ωρών σήμαινε ότι είχαμε το μέγιστο παράθυρο πριν από την επόμενη μετάβαση, γεγονός που μείωσε σημαντικά τις πιθανότητες κάποιου να χρειαστεί να δημιουργήσει μια δήλωση με πολλαπλές λογικές μετατροπές ζ Αν το είχαμε κάνει τον Μάρτιο αντί για τον Νοέμβριο, θα είχαμε εισαγάγει περισσότερες περιπτώσεις πολυπλοκότητας και περιθωρίων. Απαιτήσεις Τι είναι το 100% μη διαπραγματεύσιμο; Ποια είναι τα απόλυτα ελάχιστα που δεν μπορούν να αποκλειστούν; Σκεφτείτε τις απαιτήσεις ως τα must-haves.Όχι τα nice-to-haves, όχι τα maybe-we-should-also, αλλά τα βασικά πράγματα που πρέπει να είναι αληθινά για αυτό να αξίζει να γίνει καθόλου. Απαιτήσεις δομής ως δοκιμαστικές δηλώσεις: "Το ιστορικό συναλλαγών πρέπει να φορτώνεται σε λιγότερο από 2 δευτερόλεπτα στο p95" "Η λύση πρέπει να λειτουργεί για τους χρήστες στο iOS 14 και άνω" «Τα δεδομένα πρέπει να είναι κρυπτογραφημένα κατά τη διάρκεια της ανάπαυσης και της διέλευσης» "Δεν πρέπει να απαιτεί από κανέναν πελάτη να επαναπροσδιορίσει την ταυτότητα" Σημειώστε ότι αυτά είναι συγκεκριμένα και επαληθεύσιμα. μπορείτε να ελέγξετε αν τα έχετε ικανοποιήσει. ή Είναι άχρηστα, τα κατεβάζεις. «Πρέπει να είσαι γρήγορος» «Πρέπει να είναι ασφαλές» Bird's eye view of the solution Αμέσως βυθίζονται στις λεπτομέρειες εφαρμογής - ποια βάση δεδομένων, ποιο API, ποια υπηρεσία. Η ματιά του πουλιού θα πρέπει να είναι κατανοητή από μη τεχνικούς ενδιαφερόμενους. μιλάω για διαχειριστές προϊόντων, ανθρώπους λειτουργίας, ίσως ακόμη και οικονομικά. Αν δεν μπορείτε να εξηγήσετε τη λύση σας σε κάποιον που δεν γνωρίζει τι είναι το Kubernetes, δεν το καταλαβαίνετε αρκετά καλά. Μερικοί κανόνες για αυτό το τμήμα: Προς το παρόν όχι.Αντί say No tech talk. "Θα αναπτύξουμε μια νέα μικροεξυπηρέτηση με μια προσωρινή μνήμη Redis και θα την εκθέσουμε μέσω του GraphQL." «Θα αποθηκεύσουμε τα συχνά προσπελάσιμα δεδομένα πιο κοντά στον χρήστη, έτσι ώστε να φορτώνεται αμέσως αντί να κάνει μια αργή βόλτα στη βάση δεδομένων κάθε φορά». Τι αλλάζει από την άποψη του χρήστη; Πώς φαίνεται η επιτυχία γι 'αυτούς; Think user-centric. Start with και στη συνέχεια εξηγήστε σε υψηλό επίπεδο πώς θα το επιτύχετε. Anchor on outcomes, work backwards. Οι χρήστες θα δουν το ιστορικό συναλλαγών τους φορτώνοντας σε λιγότερο από 1 δευτερόλεπτο Μερικές φορές υπάρχουν πραγματικά διαφορετικές προσεγγίσεις. Βάλτε δύο ή τρεις επιλογές με πλεονεκτήματα και μειονεκτήματα Αυτό δείχνει ότι το έχετε σκεφτεί και δίνει στους ενδιαφερόμενους μια πραγματική επιλογή. If possible, offer multiple potential solutions. Σε αυτό το σημείο, θα πρέπει να σταματήσετε και να επανεκτιμήσετε. εδώ είναι η λίστα ελέγχου μου πριν προχωρήσουμε: [ ]Η δήλωση προβλήματος είναι σαφής και συγκεκριμένη [ ]Ο επιχειρηματικός αντίκτυπος είναι ποσοτικοποιημένος Non-goals are explicitly stated [ ] [ ] Οι απαιτήσεις είναι δοκιμαστικές [ ]Η λύση υψηλού επιπέδου έχει νόημα για έναν μη μηχανικό I'm confident this is worth doing [ ] Εάν δεν μπορείτε να ελέγξετε όλα αυτά τα κουτιά, μην προχωρήσετε στο μέρος 2 ακόμα. Σοβαρά. έχω σπαταλήσει εβδομάδες γράφοντας λεπτομερή σχέδια εφαρμογής για ιδέες που δεν άξιζαν πραγματικά να γίνουν. Getting buy-in and collaboration Το επόμενο βήμα σας είναι να λάβετε ανατροφοδότηση από βασικούς ενδιαφερόμενους. Αυτό δεν είναι μια τυπικότητα. Αυτό είναι όπου η προδιαγραφή σας είτε βελτιώνεται είτε διαλύεται. Μερικές σκληρά κερδισμένες συμβουλές για ένα επιτυχημένο pitch: Είμαι οπαδός του Notion λόγω των σχολίων και της συνεργασίας σε πραγματικό χρόνο, αλλά το Google Docs λειτουργεί επίσης. έχω ακόμη δει κάποιους αληθινούς πρωτοπόρους να χρησιμοποιούν το Figma για αυτό μια φορά! Το σημαντικό πράγμα είναι ότι οι άνθρωποι μπορούν να αφήσουν σχόλια σε γραμμή και να προτείνουν αλλαγές. Use a platform that makes collaboration easy. Εάν προτείνετε αλλαγές σε ένα ταξίδι χρήστη, δημιουργήστε mockups ή wireframes. Εάν βελτιστοποιείτε μια υπηρεσία, εμφανίστε τρέχουσες μετρήσεις με screenshots από την παρακολούθηση σας. Σας συνιστώ Figma (υψηλή πίστη) ή Excalidraw (χαμηλή πίστη) για ταξίδια χρήστη και screenshots από Grafana ή Datadog για μετρήσεις. Illustrate your points. Αφήστε το εγώ σας στην πόρτα. Κάθε κομμάτι της κριτικής που παίρνετε τώρα είναι ένα ζήτημα παραγωγής που δεν θα έχετε αργότερα. Είχα προδιαγραφές σπασμένα κατά την αναθεώρηση, και χτυπάει. Αλλά ξέρετε τι είναι χειρότερο; Κατασκευάστε κάτι για τρεις μήνες μόνο για να αποτύχει στην παραγωγή επειδή χάσατε κάτι προφανές. Getting feedback should be your main objective. Αν κάποιος αφήσει ένα σχόλιο όπως Ζητήστε τους να εξηγήσουν γιατί και να προτείνουν μια εναλλακτική λύση. Η αόριστη αρνητικότητα δεν βοηθά κανέναν. Guide your contributors. «Δεν μου αρέσει αυτή η προσέγγιση» Someone will ask Οι καλύτερες απαντήσεις έχουν αριθμούς. is a lot more compelling than Be ready to defend your value proposition. "is this worth the engineering time?" "Αυτό μπορεί να οδηγήσει σε μείωση 27% στα έξοδα φιλοξενίας βάσεων δεδομένων, με αποτέλεσμα ετήσιες εξοικονομήσεις 1,5 εκατομμυρίων στερλινών" Αυτό θα κάνει τα πράγματα πιο αποτελεσματικά». Ένα σχέδιο που αξίζει να εφαρμοστεί (μέρος 2) Αντιμετωπίζετε τις τεχνικές προδιαγραφές ως μια μοναδική προσπάθεια; Γράψτε το μόνοι σας, μοιραστείτε το για ανασκόπηση, πάρτε μερικά σχόλια, στείλτε το; Αυτό δεν είναι πώς γράφονται οι καλύτερες προδιαγραφές. The best technical specifications are the result of strong collaboration. You write the first draft, sure. But then you invite smart people to make it better. You incorporate their feedback. You adjust based on what you learn. The spec evolves. Αυτό το δεύτερο μέρος της ανατομίας είναι πιο δυναμικό. ποικίλλει ανάλογα με τον πολιτισμό της εταιρείας σας, τις πρακτικές της ομάδας σας και τον τύπο του έργου. Βέλτιστες πρακτικές και εταιρικά πρότυπα Your implementation plan should be an extension of your company's established practices. If you're using React and Next.js for web frontends, your spec should use React and Next.js. If your company has a standard CI/CD pipeline, use that. Η εξαίρεση είναι όταν προτείνετε ρητά να αλλάξετε μια καθιερωμένη πρακτική. Ίσως θέλετε να εισαγάγετε ένα νέο πλαίσιο ή να μετακινηθείτε σε μια διαφορετική βάση δεδομένων. When I've proposed changes to established practices, I always include: Έξω από την απόδειξη της ιδέας: Έχει μια άλλη εταιρεία κάνει αυτό με επιτυχία; Εμφάνιση περιπτωσιολογικών μελετών. Προηγούμενη τέχνη από γειτονικούς τομείς: Έχουμε χρησιμοποιήσει παρόμοιες προσεγγίσεις σε διαφορετικά πλαίσια; Καθαρή συλλογιστική για το γιατί η τρέχουσα προσέγγιση δεν λειτουργεί: Μην πείτε απλά «αυτό είναι καλύτερο». Διαδρομή μετανάστευσης: Πώς φτάνουμε από εδώ εκεί χωρίς να σπάσουμε τα πάντα; Στην Superbet, οδήγησα μια ομάδα που δημιούργησε μια ειδική βιβλιοθήκη UI για να αντικαταστήσει το συνεχώς προβληματικό Ant Design που χρησιμοποιούσαμε πριν. Το κάναμε ένα 100% drop-in αντικατάσταση μέσω ενός επιπέδου συμβατότητας – τεχνικά τέλεια. Αλλά ακόμα δεν κατάφερα να πείσω τις περισσότερες ομάδες να το υιοθετήσουν, επειδή δεν μπορούσα να οδηγήσω την επιχειρηματική περίπτωση στο σπίτι. Αυτό είναι το μάθημα εδώ: η αντικατάσταση της καθιερωμένης τεχνολογίας είναι δύσκολη ακόμη και όταν η λύση σας είναι αντικειμενικά καλύτερη. χρειάζεστε τους αριθμούς, τις μελέτες περιπτώσεων, τη διαδρομή μετεγκατάστασης. Προηγούμενη τέχνη και εξεταζόμενες εναλλακτικές λύσεις Υπάρχει κάτι παρόμοιο που υπάρχει ήδη; Έχετε εφαρμόσει χαρακτηριστικά με παρόμοια χαρακτηριστικά στο παρελθόν; Όλα αυτά αξίζει να αναφερθούν. Best case scenario: you discover you don't need to build anything new. You can reuse an existing solution. Attach it to the knowledge base related to the solution you found. It helps the maintainers understand who their stakeholders are and why people need this. If they want to sunset, transfer ownership, or refactor their software, they'll know who to talk to. If this happens, don't throw away your spec. Χρησιμοποιήσαμε το Statsig για να στείλουμε πειράματα, αλλά είχαμε γράψει το δικό μας SDK πάνω από αυτό αντί να χρησιμοποιήσουμε το επίσημο. Η εφαρμογή μας δεν υποστήριζε επίμονες κατανομές, πράγμα που σήμαινε ότι δεν μπορούσαμε να εκτελέσουμε κολλώδη πειράματα. Άρχισα να σκεφτόμουν πώς να προσθέσω αυτό το χαρακτηριστικό - νομίζοντας ότι θα έπρεπε να το χτίσω από το μηδέν - και πήγα σε ένα μικρό κυνήγι άγριων γαϊδούρων. What other approaches did you evaluate? Why didn't they make the cut? Αυτό δείχνει ότι έχετε κάνει τα καθήκοντά σας. εμποδίζει επίσης τους ανθρώπους να προτείνουν εναλλακτικές λύσεις που έχετε ήδη εξετάσει και απορρίψει. Approach Pros Cons Why we rejected it Use existing service X Fast, proven Doesn't support feature Y Missing critical functionality Build custom solution Perfect fit High maintenance cost Not worth the ongoing burden Third-party API Easy integration Vendor lock-in, high cost £250K annually vs £30K to build Χρησιμοποιήστε την υπάρχουσα υπηρεσία X Fast, proven Δεν υποστηρίζει το χαρακτηριστικό Y Missing critical functionality Build custom solution Τέλεια fit High maintenance cost Δεν αξίζει το συνεχές βάρος Third-party API Εύκολη ενσωμάτωση Vendor lock-in, high cost £250K annually vs £30K to build The technical approach Τώρα - επιτέλους - μπορείτε να εισέλθετε στις λεπτομέρειες.Αυτό είναι όπου εξηγείτε την πραγματική εφαρμογή, τις αρχιτεκτονικές αποφάσεις και τις επιλογές του tech stack. Architecture diagrams, sequence diagrams, data flow diagrams. I recommend (Τώρα ) because it's free and has decent collaboration features. The disadvantage is there's no live sharing like Figma, so you'll need to export and embed images. Use diagrams. Draw.io Ετικέτες.net Για τα διαγράμματα ακολουθίας, μου αρέσει το Mermaid, επειδή μπορείτε να τα γράψετε στο markdown και να τα αναπαράγετε αυτόματα στα περισσότερα εργαλεία. sequenceDiagram User->>API: Request transaction history API->>Cache: Check cache Cache-->>API: Cache miss API->>Database: Query transactions Database-->>API: Return results API->>Cache: Store in cache API-->>User: Return results Don't just say Λέει Explain the "why" behind technical decisions, not just the "what." "we'll use Redis for caching." «Θα χρησιμοποιήσουμε το Redis για την προσωρινή αποθήκευση, επειδή τα πρότυπα πρόσβασης μας είναι πολύ προσανατολισμένα στην ανάγνωση (95% ανάγνωση έναντι 5% γραφή) και χρειαζόμαστε υπο-χιλιοστό δευτερόλεπτο καθυστέρησης. Be honest about where this will break. Αυτό είναι πολύ πιο χρήσιμο από το να προσποιείστε ότι η κλίμακα της λύσης σας είναι άπειρη. Call out performance characteristics and scalability limits. "Αυτή η προσέγγιση λειτουργεί μέχρι περίπου 100.000 αιτήματα ανά δευτερόλεπτο. Show what the data looks like. Show what the API requests and responses look like. I usually include JSON examples: Mention data models, API contracts, key interfaces. { "transaction_id": "tx_123", "amount": 1250, "currency": "GBP", "timestamp": "2025-01-15T14:30:00Z", "category": "groceries" } Ένα πλεονέκτημα της ενσωμάτωσης μοντέλων σε μεταβιβάσιμη μορφή, όπως το JSON, είναι ότι αυτό μπορεί στη συνέχεια να αντιγραφεί / μεταφερθεί σε μια υπηρεσία δοκιμής ή υποκρισίας αργότερα. A benefit of embedding models in a transferrable format, like JSON is that this can then be copy/pasted into a test or mock service later on. Saves some time and cuts down on ambiguity. If this requires spinning up new services, databases, or third-party integrations, call it out. These often have cost implications and procurement delays. Highlight any new infrastructure or services needed. Breaking down the work How do you decompose this solution into milestones and tasks that can be tracked? This is project management, but it's your job to provide the structure. Ship something usable early. I'm a big fan of the MVP → MLP → Full Product progression: Split into phases that deliver incremental value. : The absolute smallest thing you can build to validate the approach. Usually internal-only or limited to a small percentage of users. MVP (Minimum Viable Product) : The smallest version that's actually good enough for real users to use and enjoy. MLP (Minimum Lovable Product) Ολόκληρο το προϊόν: Όλες οι καμπάνες και φωνές. Αυτό είναι δύσκολο να παραδεχτούμε, αλλά σε πολλές περιπτώσεις, καταλήξαμε να κρατάμε το MLP ως το τελικό αποτέλεσμα, επειδή ήταν . "good enough" Τι πρέπει να στείλετε για να λειτουργήσει αυτό; Τι είναι προαιρετικό; Χρησιμοποιήστε ένα πλαίσιο προτεραιότητας. μου αρέσει το MoSCoW (Πρέπει να έχετε, Πρέπει να έχετε, Μπορείτε να έχετε, Δεν θα έχετε). Identify critical path items vs nice-to-haves. Can the backend and frontend teams work simultaneously? Or does the backend need to ship first? Making dependencies explicit helps with planning. Call out what can be parallelised vs must be sequential. Προτιμώ τις ώρες του προγραμματιστή, τις ημέρες του προγραμματιστή, τις εβδομάδες του προγραμματιστή ως μονάδες μέτρησης, όταν συζητάμε χρονοδιαγράμματα. Εάν δεν είστε σίγουροι, κάντε μία μέτρηση, π.χ.: δεν είστε σίγουροι αν 3 ή 4 ημέρες του προγραμματιστή; Χρησιμοποιήστε 1 εβδομάδα του προγραμματιστή. Assign rough t-shirt sizes or story points if your team uses them. Χρησιμοποιήστε ένα απλό γράφημα εξαρτήσεων ή απλώς απαριθμήστε τα: Make dependencies between tasks explicit. "Η εργασία Β εξαρτάται από την ολοκλήρωση της εργασίας Α. Η εργασία C μπορεί να ξεκινήσει παράλληλα με την εργασία Β." Μετρητές επιτυχίας How will you measure if the implementation actually worked? What are the KPIs? This is where you define victory conditions. And you need to be specific. Δεν είναι μέτρο επιτυχίας. is a success metric. "Make it faster" «Μείωση της καθυστέρησης API p95 από 500ms σε κάτω από 200ms» Examples: Define measurable outcomes. Latency reduction: "p95 latency drops from 800ms to 200ms" Error rate decrease: "5xx errors drop from 0.3% to below 0.1%" Βελτίωση της μετατροπής: «Το ποσοστό ολοκλήρωσης ελέγχου αυξάνεται από 73% σε 80%» Εξοικονόμηση κόστους: «Τα έξοδα βάσης δεδομένων μειώνονται κατά £ 40K ετησίως» Πρέπει να ξέρετε από πού ξεκινάτε. παίρνω screenshots των dashboards που δείχνουν την τρέχουσα απόδοση και τις συνδέω με την προδιαγραφή. Set baseline metrics before implementation. Will you build a dashboard? Set up alerts? Run an A/B test? Be explicit about measurement methodology. Specify how you'll track these metrics. Product managers care about revenue and engagement. Engineers care about latency and throughput. Your spec should speak both languages. Include both business metrics and technical metrics. Αξιολόγηση κινδύνου, εξαρτήσεις και μετριασμός Τι μπορεί να πάει στραβά; Τι σας ανησυχεί; Τι χρειάζεστε από τις άλλες ομάδες; I've learned to be brutally honest in this section. Pretending risks don't exist doesn't make them go away. It just means you won't have a plan when they materialise. Do you need another team to ship something first? Do you rely on a third-party service that might have rate limits or downtime? Call it out. I've had projects delayed by weeks because of dependencies I didn't flag early enough. List external dependencies. Πού μπορεί να συμβεί αυτό; Τι θα συμβεί αν αυτή η κρίσιμη υπηρεσία αποτύχει; Αν εισαγάγετε μια νέα βάση δεδομένων, τι θα συμβεί αν αποτύχει; Call out single points of failure in your design. Χρησιμοποιείτε μια τεχνολογία για πρώτη φορά; Είναι αυτή μια περιοχή της βάσης κώδικα που κανείς δεν καταλαβαίνει πια πραγματικά; Κάνετε υποθέσεις σχετικά με τη συμπεριφορά των χρηστών που μπορεί να είναι λάθος; Identify areas with high uncertainty. Μην αναφέρετε μόνο τους κινδύνους - δείξτε πώς θα τους χειριστείτε. For each major risk, propose a mitigation strategy or fallback plan. Κίνδυνος: Το API τρίτου μέρους ενδέχεται να έχει χρόνο απενεργοποίησης : Implement circuit breaker with exponential backoff; cache responses for 5 minutes; have a degraded mode that works without the API Mitigation This builds trust and invites help. Είναι καλύτερο από το να προσποιείσαι ότι τα έχεις καταλάβει όλα. Be honest about what you don't know yet. "I'm not sure how we'll handle the migration of 500GB of existing data — looking for input here" Μην περιμένετε μέχρι την ανασκόπηση ασφαλείας για να διαπιστώσετε ότι χρειάζεστε μια πλήρη εκτίμηση επιπτώσεων προστασίας προσωπικών δεδομένων. Εάν αγγίζετε δεδομένα χρηστών, καλέστε το. Mention compliance, security, or data privacy concerns early. Στρατηγική Rollout How will this actually get deployed? Phased rollout? Feature flags? Canary deployments? Ποτέ δεν στέλνω μεγάλες αλλαγές στο 100% των χρηστών την πρώτη μέρα. Εάν έχετε μόνο δύο χρήστες, στείλτε μόνο έναν. If you only have two users, ship to just one. My usual progression: 5% → 10% → 50% → 100%. At each stage, you monitor metrics and watch for issues. If something breaks, you're only affecting a small subset of users. Plan for gradual rollout. Χρησιμοποιήστε τον κώδικα για την παραγωγή, αλλά κρατήστε τον πίσω από μια σημαία. Αυτό σας επιτρέπει να ελέγξετε ποιος βλέπει το νέο χαρακτηριστικό ανεξάρτητα από τη διαδικασία ανάπτυξής σας. Έχω χρησιμοποιήσει το LaunchDarkly, το Statsig και δημιούργησα εγχώριες λύσεις. Use feature flags to decouple deploy from release. What conditions trigger a rollback? Be specific: Define rollback criteria. Εάν το ποσοστό σφάλματος υπερβαίνει το 0,5%, επαναφέρετε Εάν η καθυστέρηση p95 υπερβαίνει το 1 δευτερόλεπτο, κάντε If we get more than 10 customer complaints in an hour, roll back Having these criteria defined in advance means you won't be making emotional decisions during an incident. Send real traffic through the new code path but don't show users the results. Compare the output to the old code path (also called: shadow testing). This flushes out bugs before users see them. Consider dark launching to test in production without user impact. Migrating millions of database records is risky. Do it separately from shipping new features. Ideally, migrate data first, then deploy code that uses the new schema, then clean up the old schema (expand-migrate-contract pattern). Plan for data migrations separately from code deploys. Who needs to know when this ships? Customer support team? Marketing? External partners? Write the comms plan into the spec. Have a communication plan for internal stakeholders and customers. Rollback strategy What happens if you suddenly become unavailable when everything's on fire? Would your team know how to handle it? Think of it like a preflight checklist for pilots. When stress is high and adrenaline is pumping, you don't want to be figuring things out. You want a list you can follow mechanically: Disable feature flag X Ή: μετακινηθείτε πίσω για να εκτελέσετε το abc123 και να αναπτύξετε Εκτελέστε το σενάριο βάσης δεδομένων Y για να αντιστρέψετε τις αλλαγές σχήματος Clear cache Z to remove stale data Μετρήσεις παρακολούθησης Α, Β, C για επιβεβαίωση επιτυχούς επαναφοράς Δημοσιεύσεις στο κανάλι #incidents με status Αυτό κρατά το άγχος στο ελάχιστο σε σενάρια συμβάντων. Testing approach Unit tests, integration tests, load testing, edge cases — how will you validate this actually works? Οι κρίσιμες διαδρομές χρειάζονται εκτεταμένες δοκιμές.Τα χαρακτηριστικά που είναι ωραία να έχουν μπορεί να έχουν ελαφρύτερη κάλυψη. Define test coverage expectations. If this will serve millions of requests, you need to test it at scale. I use tools like k6 or Locust to simulate load. Don't wait until production to discover your database falls over at 10,000 QPS. Plan load/performance testing for high-traffic features. Σκοτώστε τις εξαρτήσεις. Εισάγετε καθυστέρηση. Προσομοιώστε διαχωρισμούς δικτύου. Δείτε τι σπάει. Το Chaos Monkey του Netflix είναι το κανονικό παράδειγμα, αλλά δεν χρειάζεστε τίποτα που είναι εξελιγμένο. Απλά σκόπιμα σπάστε τα πράγματα και δείτε τι συμβαίνει. Consider chaos engineering for critical systems. What happens when the database is slow? When the cache is empty? When a user sends malformed input? These are where bugs hide. Test edge cases and failure modes, not just happy paths. Automated tests are great, but they only catch what you thought to test for. A human clicking around can find the weird stuff. Plan for manual QA/exploratory testing where needed. Πιστοποιητικό δοκιμής, OWASP Top 10 ελέγχους, σάρωση εξάρτησης. Εάν αγγίζετε την ταυτοποίηση, τις πληρωμές ή τα προσωπικά δεδομένα, χρειάζεστε μια ανασκόπηση ασφαλείας. Include security testing for sensitive features. Timeline and milestones Realistic estimates, buffer for unknowns, key delivery dates. Εδώ είναι μια δυσάρεστη αλήθεια: οι αρχικές σας εκτιμήσεις θα είναι λανθασμένες. είναι πάντα λανθασμένες. If there's a regulatory requirement or a conference demo, start there and work backwards to figure out if it's feasible. Work backwards from hard deadlines if they exist. If you're working in familiar territory with known tech, multiply estimates by 1.2x. If you're in unfamiliar territory or using new technology, multiply by 1.5x to 2x. I know it feels excessive, but I've never regretted padding estimates and I've always regretted being too optimistic. Pad estimates for unknowns. Every two weeks, you should be able to show something. It keeps momentum and surfaces problems early. Define clear milestones with demos or checkpoints. Holidays, conference season, compliance deadlines, marketing launches. If half your team is going to be out for a week, factor that in. Call out external constraints. Account for on-call rotations, other commitments, the fact that nobody is productive 8 hours a day. I usually assume 6 productive hours per engineer per day, and that's being generous. Be realistic about team capacity. Οι αρχικές εκτιμήσεις είναι μορφωμένες εικασίες. Καθώς μπαίνετε στην εφαρμογή, μαθαίνετε πράγματα. Ενημερώστε τη χρονολογική σας γραμμή ανάλογα. Μια προδιαγραφή θα πρέπει να είναι ένα ζωντανό έγγραφο, όχι μια σύμβαση γραμμένη σε πέτρα. Update estimates as you learn more. Open questions Τι άλλο πρέπει να γίνει; Τι άλλο πρέπει να γίνει; Αυτή η ενότητα θα πρέπει να συρρικνώνεται με την πάροδο του χρόνου καθώς λαμβάνετε απαντήσεις, αλλά είναι ζωτικής σημασίας να το έχετε. "Πρέπει να επικυρώσουμε ότι η προσέγγιση X μπορεί να χειριστεί τον όγκο ερωτήματος" ή "Πρέπει πρώτα να πρωτοτυπώσουμε το σενάριο μετεγκατάστασης σε ένα σύνολο δεδομένων δοκιμής". List unknowns that need research or prototyping before committing. "Need security team review on encryption approach" or "Need product input on what the fallback behavior should be." Call out decisions that need input from specific people or teams. "We're assuming users will click this button, but we should A/B test to confirm" or "We think this cache hit rate will be 80%, but we should measure real traffic patterns first." Highlight areas where you need to validate assumptions with data. "We could optimise for latency or throughput but not both — need to decide which matters more for this use case." Be explicit about trade-offs you haven't resolved yet. Κάποιος πρέπει να είναι υπεύθυνος για να πάρει μια απάντηση, και πρέπει να υπάρχει μια προθεσμία. Assign owners to each open question with target resolution dates. Πώς ο πολιτισμός παίζει ρόλο I've worked at companies where specs were treated as bureaucratic box-checking exercises, and I've worked at companies where they were genuinely valued as thinking tools. The difference is night and day. Αυτό μειώνει το γνωστικό φορτίο και εξασφαλίζει ότι όλοι βρίσκονται στην ίδια σελίδα. Δεν πρέπει να ανακαλύπτετε ξανά τη δομή κάθε φορά. Είχαμε ένα πρότυπο στο Notion. Για το Tandem, χρησιμοποιούμε πρότυπα του Google Docs και στο Docler, είχαμε το Confluence. Το εργαλείο δεν έχει σημασία τόσο όσο η συνέπεια. Technical specifications should be based on a standard template. Έχοντας ένα πρότυπο πρότυπο σημαίνει επίσης ότι η αναθεώρηση των προδιαγραφών είναι ευκολότερη. ξέρετε πού να αναζητήσετε τη δήλωση του προβλήματος, τις απαιτήσεις, τους κινδύνους. Μην φοβάστε να μοιραστείτε το δικό σας με ένα ευρύτερο κοινό. Ξέρω ότι είναι τρομακτικό να βάζετε τις ιδέες σας εκεί έξω, αλλά η διαφάνεια έχει τεράστια οφέλη. Άλλες ομάδες μπορεί να ανακαλύψουν ότι επιλύουν παρόμοια προβλήματα. Κάποιος από διαφορετικό κάθετο μπορεί να έχει κρίσιμο πλαίσιο που λείπει. Make all proposals publicly available. Όλες οι προδιαγραφές ήταν σε ένα κοινό χώρο έννοιας που ο καθένας στον τομέα της μηχανικής θα μπορούσε να διαβάσει.Ο αριθμός των φορές κάποιος από μια εντελώς διαφορετική ομάδα έριξε ένα σχόλιο που άλλαξε ολόκληρη την προσέγγιση ήταν αξιοσημείωτος. This serves multiple purposes: it helps others learn, it encourages collaboration, it makes people aware of what's being built across the organisation. We had monthly συνεδρίες όπου οι άνθρωποι θα παρουσιάζουν προτάσεις σε εξέλιξη και θα λαμβάνουν ανατροφοδότηση από μια διαλειτουργική ομάδα. Schedule regular review sessions of critical proposals. «Αρχιτεκτονική αναθεώρηση» Praise great proposals publicly. Acknowledge all participants, even if they just left a single comment. This encourages a culture of collaboration. I've seen teams where people were afraid to comment on specs because they thought they'd be seen as obstructionists. That's poison. You want people to feel like their input is valued, even if it's critical feedback. Tell people they're doing great. When someone writes a particularly good spec, I call it out in a public channel. Χρειάζονται πέντε δευτερόλεπτα και κάνει τους ανθρώπους να αισθάνονται καλά για τη δουλειά που κάνουν. "Αυτή η προδιαγραφή από τον Alex είναι ένα εξαιρετικό παράδειγμα του πώς να διαρθρώσετε μια σύνθετη πρόταση - ελέγξτε την για αναφορά." Το spec είναι η δουλειά Here's my final thought, and it's probably the most important thing in this entire article: writing the spec IS doing the work. Too many engineers treat the spec as overhead before the of coding begins. That's backwards. The spec is where you do the hardest thinking. It's where you discover what you don't know. It's where you find the fatal flaws before they become production incidents. "real work" The best specs I've written have been collaborative, iterative, and occasionally contentious. They've been marked up with dozens of comments. They've gone through multiple revisions. They've forced me to reconsider assumptions I didn't even know I was making. Και κάθε ένα από αυτά έκανε την εφαρμογή πιο ομαλή, ταχύτερη και πιο επιτυχημένη από ό, τι θα ήταν διαφορετικά. So the next time you're tempted to skip the spec and just start coding, resist. Open up that document. Start with the problem. Work through the details. Invite smart people to poke holes in your logic. Iterate. Your future self — and your on-call rotation — will thank you. My . It captures most of the ideas discussed here. If your organisation doesn't have a technical proposal template yet, use this as a starting point. product proposal template is available on GitHub Το πρότυπο πρότασης προϊόντος είναι διαθέσιμο στο GitHub