API दस्तावेज़ Excel या PDF में बनाकर ईमेल से साझा करने का तरीका बहुत परिचित है।
समस्या होने पर संबंधित व्यक्ति से संपर्क किया जाता है, पुराने ईमेल खोजकर ग्राहक कंपनी के पास मौजूद दस्तावेज़ का version जाँचा जाता है। बदले हुए हिस्सों को फिर से समझाया जाता है, संशोधित दस्तावेज़ भेजा जाता है, और फिर यह भी जाँचा जाता है कि वह ठीक से लागू हुआ या नहीं।
हमने इस प्रक्रिया को इतना दोहराया है कि हमें यह मूल रूप से ज़रूरी काम लगने लगा है।
लेकिन समस्या एक गलत दस्तावेज़ पर खत्म नहीं होती।
हर बार API बदलने पर नई files और emails, ग्राहक-विशेष exceptions और जिम्मेदार व्यक्ति की यादें एक-एक करके जमा होती जाती हैं। शुरुआत में यह छोटी असुविधा लगती है, लेकिन समय के साथ यह जाँचना कठिन हो जाता है कि कौन सा दस्तावेज़ मानक है, और समस्या हल करने के लिए ज़रूरी लोग और समय भी बढ़ते जाते हैं।
अगर ग्राहक कंपनी पुराने version के request format के आधार पर development करती है, तो integration errors और rework होता है। अगर mandatory fields या authentication method अलग तरह से बताए जाते हैं, तो development schedule में delay होता है, और अगर API पहले से production में है, तो data errors या outage तक हो सकते हैं।
समस्या होने के बाद ही पता चलता है कि internal development team और ग्राहक कंपनी अलग-अलग दस्तावेज़ देख रहे थे।
उसके बाद developer अपना चल रहा काम रोककर कारण जाँचता है। operations का जिम्मेदार व्यक्ति पुराने दस्तावेज़ और भेजे जाने की history खोजता है, और ग्राहक कंपनी अपने implementation और मिली हुई specification को फिर से verify करती है। एक ही document mismatch कई लोगों का काम एक साथ रोक देता है।
फिर भी ज्यादातर समस्याएँ फोन, ईमेल और messenger के जरिए चुपचाप हल हो जाती हैं।
कोई संशोधित file फिर से भेजता है, कोई ग्राहक कंपनी को स्थिति समझाता है, और developer जल्दबाज़ी में exception handling जोड़ता है। तत्काल समस्या हल हो जाती है, लेकिन यह क्यों हुई, कौन-कौन सी customer companies प्रभावित हुईं, और वही समस्या दोबारा न हो इसके लिए क्या बदला गया — यह संगठन में दर्ज नहीं रह जाता।
इस प्रक्रिया में लगने वाला समय असल में development और product improvement में लगना चाहिए था।
इससे भी बड़ी समस्या यह है कि यह पूरी प्रक्रिया किसी खास जिम्मेदार व्यक्ति के अनुभव, याददाश्त और mailbox पर निर्भर करती है। जिम्मेदार व्यक्ति छुट्टी पर हो या कंपनी छोड़ दे, तो संगठन को emails और messenger records खंगालकर काम को फिर से reconstruct करना पड़ता है।
अनमैनेज्ड API दस्तावेज़ गायब नहीं होते। वे संगठन के अंदर-बाहर बने रहते हैं और न दिखने वाला document debt बन जाते हैं।
शायद हम समस्या हल नहीं कर रहे, बल्कि हर बार समस्या होने पर लोगों के समय से उसे रोकने के तरीके के आदी हो गए हैं।
वास्तविक काम में ऐसी समस्याओं का सामना करने के बाद मैंने SpecBridge बनाया।
SpecBridge केवल API दस्तावेज़ लिखने का tool नहीं है। यह API दस्तावेज़ों के changes को review करने और केवल approved versions को customer companies और external partners को distribute करने वाला API documentation operations tool है।
इसका उद्देश्य existing Swagger को replace करना नहीं है। यह Swagger/OpenAPI और Postman Collection को import करने के बाद, external delivery process में होने वाली समस्याओं को manage करने पर focused है।
- currently distributed version और revised version के differences की comparison
- changes की review और approval
- draft और customer company को दिखने वाले distributed version को अलग रखना
- customer company के अनुसार document visibility scope manage करना
- public link password और expiry date set करना
- उसी link पर approved latest document उपलब्ध कराना
हर बार customer company को नई file भेजने की जरूरत नहीं है; internal review पूरा हुए documents को existing link पर फिर से distribute किया जा सकता है।
Developers दस्तावेज़ खोजने और फिर से भेजने वाले repetitive काम को कम कर सकते हैं, और संगठन किसी खास जिम्मेदार व्यक्ति की याददाश्त के बजाय recorded change history और distribution मानक के आधार पर API documents manage कर सकता है।
फिलहाल हम ऐसे partners खोज रहे हैं जो SpecBridge को वास्तविक API documentation operations में इस्तेमाल करें और ईमानदार feedback दें।
अगर आपकी team Excel या PDF से API documents manage करती है, या API बदलने पर हर बार customer company को दस्तावेज़ फिर से भेजती है, तो हम आपके currently used documents में से एक से साथ मिलकर validation शुरू करना चाहेंगे।
अच्छी तरह बने features की तारीफ से ज्यादा, हम वास्तविक operations में असुविधाजनक हिस्सों, अनावश्यक प्रक्रियाओं और missing features पर ईमानदार राय सुनना चाहते हैं।
अभी कोई टिप्पणी नहीं है.