GitBook ili Docusaurus: pretplata zamjenjuje stalni inženjerski rad

GitBook je bolji izbor kada startup želi brzo objavljivati dokumentaciju i uključiti suradnike koji ne rade u razvojnom okruženju. Docusaurus bolje odgovara timu kojem su važni kontrola nad kodom i prilagodba stranice, uz spremnost da održava objavu. GitBookove upute za početak pokazuju kako se sadržaj može urediti, pregledati i objaviti u pregledniku te povezati s repozitorijem.

Razlika ne završava prvom objavom. Docusaurusove upute za objavu navode da alat stvara statične datoteke, a tim bira gdje će ih posluživati i kako će ih ondje postaviti. Zato pretplatu treba usporediti s dodatnim satima za izgradnju, hosting, nadogradnje i popravke postupka objave, a ne samo s cijenom softverske licence.

Tko može objaviti ispravak

U GitBooku urednik može promijeniti uputu, pregledati je i objaviti bez lokalnog pokretanja projekta. To skraćuje put od prijavljenog problema do ispravljene stranice kada sadržaj redovito dopunjuju podrška, tim za proizvod i inženjeri. Pregled promjena i odobravanje pritom ostaju urednički posao; jednostavniji alat sam po sebi ne jamči točnost upute.

Docusaurusov sadržaj prirodno se uklapa u repozitorij, grane i zahtjeve za spajanje. To može biti prednost kada se promjena dokumentacije pregledava zajedno s promjenom proizvoda. Za suradnika koji ne koristi takav postupak tim mora osigurati način predlaganja i uređivanja sadržaja. GitBook također dopušta sinkronizaciju s GitHubom ili GitLabom, pa izbor nije podjela na dokumentaciju u repozitoriju i dokumentaciju izvan njega: važnije je koliko koraka pojedini suradnik mora proći da bi objavio ispravak.

Koliko kontrole traži dokumentacija

Docusaurus dopušta da dokumentacija dobije vlastite React komponente i sadržaj u MDX-u, uz veću slobodu u oblikovanju stranica. Usporedba alata za dokumentaciju ocjenjuje GitBook vrlo jednostavnim za učenje, Docusaurus srednje zahtjevnim, a Docusaurus prilagodljivijim kroz React. To je kvalitativna procjena, pa iz nje ne slijedi koliko će sati trebati određenom timu.

Veća prilagodljivost ima smisla kada su posebna navigacija ili interaktivne komponente stvaran zahtjev proizvoda. Svaka takva prilagodba postaje dio projekta koji treba održavati pri promjeni ovisnosti ili nadogradnji alata. GitBook nudi uži prostor za zahvate u samu izvedbu stranice, ali tim zato ima manje vlastitog koda oko dokumentacije. Ta razlika može biti važnija od početne brzine postavljanja ako se stranica treba razvijati zajedno s aplikacijom.

Verzije znače i stare upute koje treba održavati

Za API ili knjižnicu s više podržanih izdanja povijest izmjena nije zamjena za javno dostupne upute po inačicama. Docusaurusove upute o verzioniranju opisuju stvaranje zasebne kopije dokumentacije, navigacije i popisa inačica. Tim tako može ispraviti uputu za starije izdanje bez mijenjanja upute za aktualno, ali mora znati koje inačice još održava.

Takva struktura povećava broj mjesta na kojima treba provjeriti ispravak koji vrijedi za više izdanja. Docusaurusova dokumentacija zato preporučuje promišljeno uvođenje verzioniranja: ono povećava složenost projekta i trajanje izgradnje. GitBook nudi organizaciju sadržaja za različite inačice, no i ondje treba odrediti tko odlučuje koje su upute javne i kada zastarjela inačica izlazi iz uporabe. Platforma može čuvati odvojene stranice; odluka o tome što na njima piše ostaje na timu.

Pretvorite održavanje u godišnji trošak

GitBookov cjenik navodi 65 USD po stranici mjesečno uz godišnju naplatu i 12 USD po korisniku mjesečno za suradnju na plaćenom planu. Za jednu stranicu to je osnovica od 780 USD godišnje, uz 144 USD godišnje po naplativom korisniku. Objavljena dokumentacija hostana je u GitBooku, a cjenik uključuje pretraživanje sadržaja; broj javnih čitatelja nije isto što i broj naplativih suradnika.

Za Docusaurus račun treba sastaviti iz rada i usluga koje startup stvarno mora osigurati. Godišnji trošak = dodatni sati inženjerskog rada × interni trošak sata + hosting i povezane usluge. U prvoj godini zasebno uračunajte postavljanje projekta i postupka objave. U redovitom radu računajte nadogradnje, provjeru izgradnje, održavanje hostinga te rješavanje problema s objavom ili pretraživanjem. Pisanje i stručni pregled samih uputa potrebni su na obje platforme pa ih ne treba pripisati samo Docusaurusu.

Uzmimo izričito uvjetni primjer: jedna GitBookova stranica i dva naplativa korisnika prema navedenim iznosima stoje 1068 USD godišnje. Pretpostavimo da hosting Docusaurusa stoji 120 USD godišnje, a dodatni inženjerski sat 50 USD. Razlika ostavlja približno 19 sati godišnje za postavljanje i održavanje prije nego što Docusaurus dosegne isti iznos. Pretpostavljeni hosting i satnica nisu tržišne cijene za Hrvatsku; rezultat pokazuje kako se iz vlastitih ulaznih podataka dobiva usporediv prag.

Taj prag ovisi i o postojećoj infrastrukturi. Tim koji već objavljuje statične stranice kroz stabilan postupak može imati malo dodatnog rada, dok tim bez takvog postupka mora preuzeti konfiguraciju, odgovornost za objavu i njezine buduće popravke. Zato računajte samo sate koje izbor platforme dodaje: ako se isti CI sustav već održava za proizvod, njegov puni trošak ne pripada dokumentaciji. Posebno odvojite jednokratnu izgradnju od rada koji će se ponavljati svake godine.

Gdje se izbor prelama

GitBook ima prednost kada dokumentacija često traži brze uredničke ispravke, a suradnici dolaze iz više timova. Pretplata tada pokriva gotov postupak uređivanja i objave. Docusaurus je snažniji izbor kada su prilagođene komponente, sadržaj uz kod proizvoda i vlastita pravila objave važni zahtjevi, a tim ima osobu odgovornu za nadogradnje i hosting.

Odluku može preokrenuti i broj suradnika ili stranica, jer povećava pretplatu, kao i opseg prilagodbi, jer povećava rad na Docusaurusu. Za startup koji bira između te dvije platforme presudna je stoga procjena ponavljajućeg rada nakon pokretanja: upravo ondje besplatna licenca može postati skuplji izbor, a pretplata uštedjeti inženjersko vrijeme.

Pročitajte i:

• GA4 ili Matomo: integracije protiv vlasništva nad podacima
• Financiranje iz prihoda ili VC: bez razrjeđenja ne znači jeftin kapital
• n8n ili Zapier: kontrola infrastrukture nasuprot 9.000 integracija