टैग वाले लेख: कंटेंट मॉडल
Sphinx, MkDocs, Astro और दूसरे generators अलग content models और teams के लिए बने हैं। Authoring workflow, extensibility, localization और maintenance cost के आधार पर चुनें, demo की चमक के आधार पर नहीं।
पचास पेज पर काम करने वाली संरचना पाँच सौ पेज पर टूट सकती है। नेविगेशन को user tasks, content types और स्थायी concepts के आधार पर बनाइए, संगठन के chart के आधार पर नहीं। छोटी documentation लगभग किसी भी navigation के साथ चल सकती है। बीस पेज हों तो reader पूरा menu देख सकता है, writers को याद रहता है कि क्या कहाँ है और duplicate content भी दिख जाता है। पाँच सौ पेज पर ये फायदे खत्म हो जाते हैं। तब structure खु…
OpenAPI description accurate reference structure generate कर सकती है, लेकिन developers को concepts, task flows, authentication, examples और failure recovery भी चाहिए जिन्हें schema अकेले नहीं समझा सकता। OpenAPI operations, parameters, request/response shapes, status codes और reusable schemas बहुत अच्छी तरह describe करता है। इसलिए generated reference और automated validation के लिए यह मजबूत source है।
Scale पर consistency content models, terminology और reusable patterns से आती है, विशाल style guide याद कराने से नहीं। Important rules को schemas और components में encode करें। Small team shared habits और direct editing पर चल सकती है। दर्जनों या सैकड़ों contributors के साथ memory control system नहीं रह सकती। Rules publishing environment में रहने चाहिए।