GitBook ή ReadMe: η API κονσόλα κοστίζει διαφορετικά από τη συνεργασία

Αν η τεκμηρίωση οργανώνεται κυρίως γύρω από endpoints, δοκιμές κλήσεων και δεδομένα χρήσης της API, το ReadMe είναι η πιο στοχευμένη επιλογή. Αν η ομάδα συντηρεί παράλληλα οδηγούς προϊόντος και αναφορά API, με συνεισφορές από προγραμματιστές και τεχνικούς συντάκτες, το GitBook ταιριάζει καλύτερα στη δομή της δουλειάς της. Και οι δύο υπηρεσίες υποστηρίζουν διαδραστική αναφορά API· η διαφορά βρίσκεται στο τι αποτελεί τον πυρήνα της τεκμηρίωσης.

Η τιμή εξαρτάται από διαφορετικές μονάδες. Στο GitBook μετρούν τα δημοσιευμένα sites και οι χρήστες της ομάδας. Στο ReadMe η δημόσια τιμολόγηση διακρίνει το project από τους διαχειριστές του. Μια επιλογή που φαίνεται οικονομική για ένα developer hub μπορεί επομένως να αλλάξει όταν προστεθούν ανεξάρτητοι προορισμοί τεκμηρίωσης ή περισσότεροι άνθρωποι στη διαδικασία έγκρισης.

Πόσο κεντρική είναι η διαδραστική αναφορά API;

Το ReadMe ταιριάζει όταν ο προγραμματιστής ανοίγει την τεκμηρίωση για να εντοπίσει μια λειτουργία και να δοκιμάσει την κλήση της. Η περιγραφή του API Explorer εξηγεί ότι μια προδιαγραφή OpenAPI μετατρέπεται σε διαδραστική αναφορά, από την οποία ο επισκέπτης μπορεί να στείλει πραγματικές κλήσεις. Η αναφορά λειτουργεί έτσι ως μέρος της πρώτης επαφής με την API, μαζί με τους οδηγούς εκκίνησης και αυθεντικοποίησης.

Το GitBook επιτρέπει επίσης δοκιμή endpoints μέσα στην τεκμηρίωση. Οι οδηγίες OpenAPI του GitBook περιγράφουν δύο τρόπους οργάνωσης: αυτόματη δημιουργία σελίδων από την προδιαγραφή ή εισαγωγή επιλεγμένων λειτουργιών σε υπάρχουσες σελίδες. Η δεύτερη δυνατότητα είναι χρήσιμη όταν μια κλήση χρειάζεται να εμφανίζεται δίπλα στην εργασία που εξηγεί ένας οδηγός προϊόντος, αντί να βρίσκεται μόνο σε χωριστή αναφορά.

Η ουσιαστική διάκριση αφορά τη διαδρομή του αναγνώστη. Σε μια υπηρεσία όπου οι περισσότεροι επισκέπτες αναζητούν μεθόδους, παραμέτρους και απαντήσεις, η ποιότητα της αναφοράς API έχει προτεραιότητα. Όταν ξεκινούν από μια εργασία, όπως η σύνδεση μιας εφαρμογής ή η ρύθμιση μιας λειτουργίας, μεγαλύτερο βάρος έχει η συντήρηση οδηγών που ενσωματώνουν τις σχετικές κλήσεις. Η παρουσία playground και στις δύο πλατφόρμες δεν λύνει από μόνη της αυτή την εκδοτική επιλογή.

Ποια δεδομένα χρειάζεται η ομάδα για την API και τους οδηγούς;

Το ReadMe συνδέει στοιχεία για την API με στοιχεία για την τεκμηρίωση. Τα metrics του ReadMe περιλαμβάνουν όγκο κλήσεων, χρήση endpoints και σφάλματα, αλλά και προβολές σελίδων, αναζητήσεις και σχόλια. Αυτές είναι διαφορετικές ενδείξεις: μια συχνή αναζήτηση μπορεί να φανερώνει κενό στους οδηγούς, ενώ τα σφάλματα μιας λειτουργίας δείχνουν πού δυσκολεύονται οι χρήστες της API.

Για μια ομάδα developer relations, η σύνδεση αυτών των δεδομένων βοηθά να ξεχωρίσει τη δημοφιλή σελίδα από τη δύσκολη ενσωμάτωση. Ο αριθμός προβολών, για παράδειγμα, δεν αρκεί για να δείξει αν οι κλήσεις ενός endpoint ολοκληρώνονται όπως αναμένεται. Αν η ομάδα αξιολογεί κυρίως την πλοήγηση και την ποιότητα των οδηγών, τα analytics τεκμηρίωσης έχουν μεγαλύτερη βαρύτητα. Αν προτεραιότητα είναι η χρήση και τα σφάλματα της API, χρειάζεται να συνεκτιμήσει τα δεδομένα κλήσεων.

Πώς υπολογίζεται το κόστος ανά site και συντάκτη;

Το τιμολόγιο του GitBook δίνει για το Essential $65 ανά site και $12 ανά χρήστη τον μήνα, ως μηνιαίο ισοδύναμο ετήσιας χρέωσης. Η Free βαθμίδα περιλαμβάνει έναν χρήστη, διαδραστική τεκμηρίωση API και αμφίδρομο Git Sync με GitHub ή GitLab. Δεν περιλαμβάνει ταυτόχρονη συνεργατική επεξεργασία ούτε ανασκόπηση και έγκριση αλλαγών· αυτές οι λειτουργίες περιλαμβάνονται στο Essential. Το κόστος συνεργασίας προκύπτει επομένως από τους χρήστες και την απαιτούμενη βαθμίδα, όχι από την απλή ύπαρξη API playground.

Με τις δημοσιευμένες τιμές, ένα υποθετικό Essential site και τρεις χρήστες αντιστοιχούν σε $101 τον μήνα: $65 για το site και $36 για τους χρήστες. Αν οι ίδιοι άνθρωποι δημοσιεύουν δύο Essential sites, το αντίστοιχο ποσό γίνεται $166, επειδή προστίθεται δεύτερη χρέωση site και όχι δεύτερη χρέωση για τους ίδιους χρήστες. Πρόκειται για υπολογισμούς με ετήσια χρέωση, πριν από τυχόν φόρους ή πρόσθετες υπηρεσίες. Η διάκριση έχει σημασία για εταιρεία που διατηρεί, για παράδειγμα, χωριστή τεκμηρίωση προϊόντος και developer portal.

Στο τιμολόγιο του ReadMe, το δωρεάν Starter περιλαμβάνει ένα project, διαδραστική αναφορά API, αμφίδρομο συγχρονισμό και metrics χρήσης, αλλά έναν διαχειριστή. Το Pro κοστίζει $250 τον μήνα με ετήσια χρέωση, περιλαμβάνει ένα project και έως πέντε διαχειριστές, ενώ κάθε επιπλέον διαχειριστής κοστίζει $20 τον μήνα. Στο Pro προστίθενται η πρόσκληση συνεργατών, η ταυτόχρονη επεξεργασία, τα branches και οι αναθεωρήσεις. Τα πολλαπλά συνδυασμένα projects εμφανίζονται στη βαθμίδα Enterprise, για την οποία ζητείται προσφορά.

Ένα υποθετικό Pro project με έξι διαχειριστές φτάνει έτσι τα $270 τον μήνα με τους παραπάνω όρους. Το ποσό δεν συγκρίνεται αυτομάτως με την τιμή ενός GitBook site: το project και το site περιγράφουν διαφορετική οργάνωση δημοσίευσης. Ούτε ο αριθμός των συντακτών ταυτίζεται αναγκαστικά με τον αριθμό των διαχειριστών. Για μια δίκαιη σύγκριση χρειάζεται πρώτα να οριστεί ποιος δημοσιεύει, ποιος εγκρίνει και πόσοι ανεξάρτητοι προορισμοί τεκμηρίωσης απαιτούνται.

Ποια ροή δημοσίευσης καθορίζει την επιλογή;

Για ένα developer hub όπου κυριαρχεί η αναφορά API, η αρχική επιλογή είναι το ReadMe: η διαδραστική δοκιμή και τα δεδομένα χρήσης βρίσκονται στην ίδια εμπειρία με τους οδηγούς. Το Starter καλύπτει την αρχική δημοσίευση από έναν διαχειριστή. Όταν όμως χρειάζονται συντάκτες που επεξεργάζονται ταυτόχρονα και διαδικασία αναθεώρησης, το σχετικό κόστος μεταφέρεται στο Pro. Αν απαιτούνται πολλαπλά συνδυασμένα projects, η δημόσια τιμή του Pro δεν αρκεί για πλήρη προϋπολογισμό.

Για μικτή τεκμηρίωση, το GitBook έχει ισχυρότερη λογική όταν οι οδηγοί προϊόντος, οι επιλεγμένες λειτουργίες OpenAPI και οι αλλαγές μέσω Git πρέπει να συντηρούνται μαζί. Το αμφίδρομο Git Sync επιτρέπει συνεισφορές από το αποθετήριο και τον οπτικό επεξεργαστή, ενώ οι πληρωμένες βαθμίδες προσθέτουν συνεργατική επεξεργασία και εγκρίσεις. Η ομάδα πρέπει να υπολογίσει χωριστά την αύξηση των sites και των χρηστών, ακόμη κι αν η αναφορά API παραμένει η ίδια.

Η απόφαση εξαρτάται τελικά από το ποια εργασία θα επαναλαμβάνεται συχνότερα: δοκιμή και παρακολούθηση endpoints ή συγγραφή και έγκριση μικτού περιεχομένου. Έπειτα έρχεται η μονάδα που θα αυξάνεται καθώς μεγαλώνει η τεκμηρίωση: site και χρήστης στο GitBook, project και διαχειριστής στο ReadMe. Αυτή η διάκριση δείχνει τόσο ποια λειτουργία θα εξυπηρετεί καθημερινά την ομάδα όσο και πού θα εμφανιστεί η επόμενη αύξηση κόστους.

Διαβάστε επίσης:

• Deel ή Remote: η διαφορά των $100 κρύβει μεγαλύτερη δέσμευση κεφαλαίου
• Ασύγχρονη συνεργασία: λιγότερες συσκέψεις, αλλά μεγαλύτερος κίνδυνος σιλό
• Τοπικό LLM ή cloud API: το cache μπορεί να ανατρέψει το κόστος