Diátaxis: גישה שיטתית לכתיבת תיעוד טכני

Diátaxis היא גישה שיטתית לכתיבת תיעוד טכני. מחברתה, דניאלה פרוצ׳ידה, מציג אותה כדרך לחשוב על תיעוד ולעשות אותו: היא מגדירה גישות לתוכן, לארכיטקטורה ולצורה, הנובעות מחקר הצרכים של משתמשי התיעוד.

ארבעה סוגי תיעוד

הרעיון המרכזי הוא שקיימים ארבעה סוגים מהותיים ושונים של תיעוד, העונים לארבעה צרכים שונים: מדריכי למידה (tutorials), מדריכים מעשיים (how-to guides), תיעוד עיוני (reference) והסברים (explanation). לכל אחד מטרה משלו, וכל אחד צריך להיכתב באופן אחר. מדריך למידה הוא שיעור שלוקח את הלומד ביד דרך חוויית למידה — הוא תמיד מעשי, כמו שיעור נהיגה. מדריך מעשי פונה למשתמש שכבר מיומן ומסייע לו להשיג מטרה או לפתור בעיה בעולם האמיתי; הוא עוסק בעבודה ולא בלימוד. תיעוד עיוני מכיל את העובדות הטכניות הדרושות לפעולה נכונה — מדויקות, מלאות וללא פרשנות, כמו מפת ים. ההסבר לעומתו מספק הקשר ורקע, מחבר בין הדברים ועונה על השאלה “למה”.

מפה ומצפן

Diátaxis מסדרת את ארבעת הסוגים על מפה מושגית ומוסיפה מצפן שמסייע להחליט היכן צריך להימצא כל תוכן. מדריכי למידה ומדריכים מעשיים נוגעים למה שהמשתמש עושה — פעולה; תיעוד עיוני והסברים נוגעים למה שהמשתמש יודע — הכרה. מדריכי למידה והסברים משרתים רכישת מיומנות, כלומר לימוד, ואילו מדריכים מעשיים ותיעוד עיוני משרתים יישום של מיומנות, כלומר עבודה. לפי הפרויקט, דווקא חצייתם או טשטושם של הגבולות האלה עומדים בלב מספר עצום של בעיות בתיעוד.

מוכח בשטח

הגישה מוצגת כקלת משקל, קלה להבנה וללא כפייה של מגבלות טכניות, והיא מיושמת בהצלחה במאות פרויקטי תיעוד. גרג פרילו מ-Vonage מספר ש-Diátaxis אפשר לבנות תיעוד פנימי באיכות גבוהה; מייגן סאליבן מספרת שפרויקט Gatsby נשען על המסגרת בעת ארגון מחדש של התיעוד בקוד הפתוח, וארבעת הרביעים עזרו לתעדף סוגי מסמכים; ואדם שוורץ מזכיר שבזמן עיצוב מחדש של תיעוד המפתחים של Cloudflare הפכה Diátaxis ל“כוכב הצפון של הארכיטקטורה של המידע שלנו”.

איך מתחילים

עצת האתר עצמו: להתחיל ביישום — על משהו, ולו הקטן ביותר. לופ העבודה המומלץ הוא להביט בתיעוד שנמצא מולכם, לשאול אם יש דרך לשפר אותו, לבחור דבר אחד שאפשר לעשות ממש עכשיו — ולעשות אותו; ואז לחזור על כך. אין צורך להאמין בתיאוריה: המחבר מציג אותה כגישה פרגמטית לחלוטין, שכל ערכה בעזרה לאנשים ליצור תיעוד טוב יותר.