فرض کنید تیم Design System برای یکی از Componentها مستندات کاملی نوشته است. تمام Variantها معرفی شدهاند، Stateها توضیح داده شدهاند، Props در دسترس هستند، مثالهای مختلف وجود دارند و حتی نکات مربوط به Accessibility هم ثبت شدهاند.
چند روز بعد یکی از Designerها در گروه تیم میپرسد:
برای این سناریو باید از Modal استفاده کنم یا Drawer؟
کمی بعد یک Developer سؤال میکند:
این Component در حالت Loading چه رفتاری داره؟
و عضو جدید تیم هم میپرسد:
از کجا بفهمم کدوم Variant برای Use Case من مناسبه؟
اولین واکنش ممکن است این باشد که بگوییم: «همه اینها توی Documentation نوشته شده.»
اما اگر اطلاعات وجود دارد و افراد همچنان سؤال میپرسند، شاید مشکل کمبود Documentation نباشد. شاید مسئله این باشد که مستندات را نوشتهایم، اما تجربه استفاده از آن را طراحی نکردهایم.
کامل بودن Documentation با قابل استفاده بودن آن فرق دارد
وقتی کیفیت Documentation را بررسی میکنیم، معمولاً به مقدار اطلاعات نگاه میکنیم. آیا تمام Componentها مستند شدهاند؟ آیا Props توضیح دارند؟ آیا Do/Don't داریم؟ آیا مثال گذاشتهایم؟
اینها مهماند، اما کامل بودن محتوا فقط یک بخش از مسئله است.
یک صفحه میتواند تمام اطلاعات لازم را داشته باشد، اما Designer برای پیدا کردن پاسخ یک سؤال ساده مجبور باشد چند دقیقه بین Sectionهای مختلف بگردد. از نظر تیم Design System مستندات کامل است، اما از نظر کسی که وسط یک Task واقعی قرار دارد، Documentation کار خودش را انجام نداده است.
درواقع سؤال مهم فقط این نیست که:
آیا این اطلاعات در Documentation وجود دارد؟
بلکه باید بپرسیم:
آیا کسی که به این اطلاعات نیاز دارد میتواند در زمان مناسب آن را پیدا کند، بفهمد و استفاده کند؟
این تفاوت کوچک، نگاه ما به Documentation را کاملاً تغییر میدهد.
مستندات Design System فقط یک مرجع اطلاعات نیست
اگر Documentation را فقط جایی برای ذخیره اطلاعات ببینیم، طبیعی است که هدفمان اضافه کردن محتوای بیشتر باشد. هر بار سؤال جدیدی مطرح میشود، Section دیگری اضافه میکنیم و هر بار Use Case تازهای پیدا میشود، مثال دیگری در صفحه قرار میدهیم.
بعد از مدتی مستندات واقعاً کاملتر شدهاند، اما لزوماً قابل استفادهتر نشدهاند.
چون Documentation خودش یک محصول داخلی است.
کاربر دارد، مسئله دارد، Journey دارد و حتی Search و Information Architecture برایش اهمیت دارد. کسی که وارد مستندات میشود معمولاً برای مطالعه آزاد نیامده است؛ میخواهد یک تصمیم بگیرد یا یک مشکل را حل کند.
مثلاً Designer میخواهد بداند برای انتخاب از میان تعداد زیادی گزینه از Select استفاده کند یا Combobox. Developer میخواهد بفهمد Component موردنظر API لازم برای Use Case او را دارد یا نه. عضو جدید تیم هم شاید اصلاً نداند برای مسئلهای که دارد باید دنبال چه اصطلاحی بگردد.
پس Documentation فقط باید اطلاعات را نگهداری نکند؛ باید افراد را به پاسخ برساند.
یک Documentation برای چند کاربر متفاوت نوشته میشود
یکی از دلایلی که مستندات Design System میتواند پیچیده شود این است که مخاطب واحدی ندارد.
Designer، Developer و Contributor ممکن است وارد صفحه مربوط به همان Component شوند، اما سؤال یکسانی ندارند.
یک Designer بیشتر میخواهد بداند Component چه زمانی مناسب است، چه زمانی نباید از آن استفاده کند، کدام Variant برای مسئله او بهتر است، چه Patternهایی باید رعایت شوند و رفتار آن در شرایط مختلف چگونه است.
در مقابل، Developer ممکن است دنبال API، Props، Stateها، Dependencyها، Accessibility، نمونه Code و تغییرات نسخه جدید باشد.
کسی که قصد Contribution دارد سؤال دیگری دارد. او باید بداند چه چیزی قابل تغییر است، برای اضافه کردن Use Case جدید چه فرآیندی وجود دارد، چه تستهایی لازم است و چه کسی تغییر را Review میکند.
اگر تمام این اطلاعات بدون ساختار مشخص در یک صفحه قرار بگیرند، ممکن است Documentation از نظر حجم بسیار کامل باشد، اما هر مخاطب برای رسیدن به بخش کوچکی که نیاز دارد مجبور شود از میان اطلاعات مربوط به دیگران عبور کند.
پس شاید سؤال قبل از نوشتن هر بخش این باشد:
این اطلاعات برای چه کسی و برای انجام چه کاری نوشته میشود؟
ساختار Documentation باید از سؤالهای واقعی تیم شروع شود
خیلی وقتها Documentation را براساس ساختار خود Design System سازماندهی میکنیم. صفحهای برای Components داریم، بخشی برای Tokens، بخشی برای Foundations و قسمتی برای Guidelines.
این ساختار برای تیمی که Design System را ساخته کاملاً منطقی است، چون با مدل ذهنی خود سیستم هماهنگ است.
اما مصرفکننده همیشه با همین مدل ذهنی وارد نمیشود.
ممکن است Designer اصلاً نداند چیزی که دنبالش میگردد Component است، Pattern است یا Guideline. او فقط میداند:
میخواهم قبل از یک اقدام خطرناک به کاربر هشدار بدهم.
اگر برای پیدا کردن جواب ابتدا مجبور باشد تشخیص دهد این مسئله زیرمجموعه Feedback است، Dialog است، Destructive Actions است یا Patterns، پیدا کردن پاسخ سختتر میشود.
به همین دلیل، بخشی از Documentation میتواند علاوه بر ساختار سیستم، براساس مسئله و Task کاربر هم قابل کشف باشد.
مثلاً بهجای اینکه فقط بگوییم «این Modal است و این API آن است»، باید به کاربر کمک کنیم بفهمد چه زمانی Modal اصلاً انتخاب مناسبی است.
یک Search خوب زمانی مهم میشود که کاربر اسم جواب را نمیداند
داشتن Search در Documentation مفید است، اما Search هم همیشه مشکل Discoverability را حل نمیکند.
فرض کنید Designer نمیداند Pattern موردنظر در سیستم با چه نامی ثبت شده است. او عبارت «حذف اطلاعات» را جستوجو میکند، اما Documentation آن را تحت عنوان Destructive Actions ثبت کرده است.
از نظر فنی اطلاعات وجود دارد؛ از نظر عملی کاربر نمیتواند آن را پیدا کند.
این مسئله مخصوصاً برای اعضای جدید تیم مهمتر است، چون هنوز Vocabulary داخلی Design System را نمیشناسند.
یک Documentation قابل استفاده باید تا حدی بتواند فاصله میان زبانی که تیم Design System استفاده میکند و زبانی که مصرفکننده با آن مسئلهاش را توصیف میکند کاهش دهد.
استفاده از Aliasها، Keywordهای مرتبط، لینک بین صفحات و مثالهای مبتنی بر Use Case میتواند در چنین شرایطی بسیار مهمتر از اضافه کردن یک پاراگراف توضیح جدید باشد.
مستندات نباید فقط Component را توضیح دهند؛ باید به تصمیم کمک کنند
فرض کنید صفحه مربوط به Modal تمام مشخصات آن را توضیح داده است. Anatomy، Size، Spacing، Props و Stateها همگی مشخص هستند.
اما سؤال Designer این نیست که Modal چطور ساخته شده است.
سؤالش این است:
آیا اصلاً باید برای این مسئله از Modal استفاده کنم؟
اگر Documentation فقط نحوه استفاده از Component را توضیح دهد، کاربر هنوز باید تصمیم اصلی را خودش از صفر بگیرد.
اینجاست که بخشهایی مثل When to use، When not to use، Alternatives، Do/Don't و مثالهای Contextual اهمیت پیدا میکنند.
مثلاً اگر کاربر برای یک Task پیچیده به فضای زیادی نیاز دارد، شاید Modal انتخاب مناسبی نباشد. اگر فقط میخواهد یک Feedback کوتاه نمایش دهد، شاید اصلاً نیازی به Modal وجود نداشته باشد.
مستندات خوب فقط نمیگویند «این ابزار چگونه کار میکند»؛ کمک میکنند بفهمیم «آیا این ابزار برای مسئله من مناسب است یا نه.»
مثال زیاد همیشه Documentation را بهتر نمیکند
ممکن است برای حل مشکل، تعداد زیادی مثال به Documentation اضافه کنیم. اما اگر مثالها فقط Variationهای بصری باشند، باز هم کاربر ممکن است نتواند آنها را به مسئله خودش ارتباط دهد.
مثلاً نمایش پنج مدل مختلف از Empty State مفید است، اما ارزش بیشتری ایجاد میشود اگر توضیح دهیم چرا هرکدام متفاوتاند.
یک Empty State ممکن است برای اولین ورود کاربر باشد و هدفش Onboarding باشد. نمونه دیگر ممکن است نتیجه Filter باشد و Action مناسب آن Reset کردن Filterها باشد. نمونه سوم شاید مربوط به نداشتن Permission باشد و اصلاً نباید CTA ایجاد محتوا داشته باشد.
در این حالت مثالها فقط چیزی برای کپی کردن نیستند؛ منطق انتخاب راهحل را هم منتقل میکنند.شاید سؤالهای تکراری تیم بهترین Research برای Documentation باشند
یکی از منابع ارزشمند برای بهتر کردن Documentation همان سؤالهایی هستند که تیم Design System بارها دریافت میکند.
اگر افراد مرتب میپرسند «فرق این دو Component چیه؟»، شاید Comparison مناسبی در Documentation نداریم. اگر سؤال دائمی این است که «کدوم Variant رو استفاده کنم؟»، شاید Usage Guidance ضعیف است. اگر Developerها مرتب درباره Migration سؤال دارند، شاید Release Documentation کافی نیست.
در چنین شرایطی سؤال تکراری را نباید صرفاً با فرستادن لینک پاسخ دهیم.
خود سؤال یک Signal است.
اگر پنج نفر نتوانستهاند پاسخ را پیدا کنند، احتمال دارد نفر ششم هم نتواند. بنابراین Support Channel، Commentهای Figma، Issueها و حتی سؤالهایی که در جلسههای Design Review مطرح میشوند میتوانند نوعی Research برای Documentation باشند.
بهجای اینکه فقط بپرسیم «چه چیزی هنوز مستند نشده؟»، میتوانیم بررسی کنیم:
تیمها برای پیدا کردن چه پاسخهایی هنوز به یک انسان نیاز دارند؟
این سؤال معمولاً مشکلات Documentation را خیلی سریعتر آشکار میکند.
پیدا کردن جواب فقط نیمی از مسئله است
حتی اگر کاربر پاسخ را پیدا کند، باید بتواند به آن اعتماد کند.
فرض کنید Documentation میگوید Component سه Variant دارد، اما در Figma چهار Variant وجود دارد. نمونه Code رفتار دیگری نشان میدهد و نسخه Production هم هنوز از API قبلی استفاده میکند.
در این شرایط، مشکل دیگر Discoverability نیست؛ مشکل اعتماد است.
بعد از چند بار مواجه شدن با اطلاعات قدیمی، رفتار کاربر تغییر میکند. بهجای مراجعه به Documentation، مستقیماً از یکی از اعضای تیم Design System سؤال میکند، چون پاسخ انسانی را قابلاعتمادتر میداند.
از اینجا به بعد حتی اگر Documentation را اصلاح کنیم، برگرداندن عادت قبلی ساده نیست.
به همین دلیل، کیفیت Documentation فقط به میزان جزئیات آن وابسته نیست؛ Freshness و هماهنگی آن با Design و Code هم بخشی از تجربه Documentation است.
شاید لازم باشد موفقیت Documentation را متفاوت اندازه بگیریم
اگر فقط تعداد صفحات مستندشده را اندازه بگیریم، ممکن است به نتیجه اشتباهی برسیم. مثلاً بگوییم ۹۵ درصد Componentها Documentation دارند و بنابراین وضعیت بسیار خوبی داریم.
اما اگر تیمها همچنان برای سؤالهای روزمره به اعضای Design System پیام میدهند، عدد ۹۵ درصد داستان کاملی تعریف نمیکند.
برای ارزیابی بهتر میتوانیم به رفتار واقعی تیمها نگاه کنیم. آیا افراد پاسخ را بدون کمک پیدا میکنند؟ پیدا کردن آن چقدر طول میکشد؟ چه سؤالهایی مرتب تکرار میشوند؟ کدام صفحات بیشترین Search ناموفق را دارند؟ آیا بعد از خواندن صفحه، افراد میتوانند Component مناسب را انتخاب کنند؟
حتی میتوان روی Documentation یک Usability Test ساده انجام داد.
مثلاً به Designer بگوییم:
برای این سناریو باید بین Modal و Drawer تصمیم بگیری. با استفاده از Documentation مشخص کن کدام گزینه مناسبتر است.
مشاهده اینکه کاربر از کجا شروع میکند، چه چیزی را جستوجو میکند و کجا گیر میکند، میتواند اطلاعاتی بدهد که تعداد Page Viewها هیچوقت نشان نمیدهند.
Documentation خوب لزوماً Documentation بزرگ نیست
گاهی بهترین بهبود، اضافه کردن محتوا نیست؛ حذف کردن، مرتب کردن یا قابلکشف کردن محتوای موجود است.
ممکن است سه صفحه مختلف درباره یک موضوع داشته باشیم که هیچکدام منبع اصلی مشخصی نیستند. ممکن است اطلاعات مهم در انتهای صفحهای بسیار طولانی پنهان شده باشند یا اصطلاحاتی استفاده کرده باشیم که فقط اعضای تیم Design System آنها را میشناسند.
در چنین شرایطی نوشتن Documentation بیشتر میتواند مشکل را بزرگتر کند.
شاید چیزی که نیاز داریم Content Audit باشد؛ بررسی کنیم چه چیزی استفاده میشود، چه چیزی قدیمی است، چه صفحات همپوشانی دارند و چه اطلاعاتی باید در جای دیگری قرار بگیرند.
همانطور که Component Library را Maintenance میکنیم، Documentation هم به Maintenance نیاز دارد.
Documentation را هم باید مثل یک Product طراحی کنیم
اگر Documentation را یک Product داخلی ببینیم، نگاه ما به آن تغییر میکند.
دیگر فقط نمیپرسیم چه اطلاعاتی باید بنویسیم. به این فکر میکنیم که کاربرانش چه کسانی هستند، با چه هدفی وارد میشوند، چه Taskهایی دارند، کجا گیر میکنند، چه چیزی را نمیتوانند پیدا کنند و چه زمانی ترجیح میدهند بهجای Documentation از یک همکار سؤال کنند.
حتی میتوانیم Journey سادهای برای آن تصور کنیم: کاربر مسئلهای دارد، وارد Documentation میشود، راهحل احتمالی را پیدا میکند، تفاوت گزینهها را میفهمد، تصمیم میگیرد و در نهایت Component یا Pattern مناسب را استفاده میکند.
اگر در هرکدام از این مراحل شکست بخورد، صرف وجود اطلاعات کافی نیست.
جمعبندی
مشکل خیلی از Documentationهای Design System این نیست که اطلاعات کمی دارند. گاهی دقیقاً برعکس است؛ اطلاعات زیادی دارند، اما پیدا کردن پاسخ در میان آنها سخت شده است.
یک Documentation خوب فقط باید کامل نباشد؛ باید قابل پیدا کردن، قابل فهم، قابل اعتماد و متناسب با نیاز مخاطب باشد.
برای رسیدن به این نقطه شاید لازم باشد کمتر از خودمان بپرسیم:
چه چیز دیگری باید مستند کنیم؟
و بیشتر بپرسیم:
تیمها وقتی با یک مسئله واقعی روبهرو میشوند، آیا میتوانند بدون کمک ما جوابشان را پیدا کنند؟
اگر پاسخ منفی است، احتمالاً مشکل با نوشتن یک صفحه دیگر حل نمیشود؛ چون Documentation هم مثل هر محصول دیگری، قبل از محتوای بیشتر به تجربه بهتر نیاز دارد.
کامنتها
…