בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון בקוד פתוח:
- WordPress
- כותבים טכניים:
- tacitonic
- שם הפרויקט:
- מדריך סגנון מלא וחודשי של מסמכי תיעוד
- אורך הפרויקט:
- Long running (5 months)
תיאור הפרויקט
תקציר:
WordPress הוא ארגון תוכנה בינלאומי ללא מטרות רווח, שמטרתו לספק לקהילות ברחבי העולם תוכנה שמתמקדת בנגישות, בביצועים, באבטחה ובקלות השימוש. מטרת WordPress היא להפוך את עולם הפרסום ותוכנות הקוד הפתוח באינטרנט לדמוקרטיים. בעידן הדיגיטלי שלנו, אתר הוא ממש הפנים של ארגון או אדם באינטרנט. מערכת WordPress עומדת במשימה העצומה של מתן שירות יעיל למאות מיליוני משתמשים – 35% מהאינטרנט פועל באמצעות התוכנה שלה. כדי לספק שירות יעיל יותר למשתמשים האלה, התיעוד הוא חיוני ורוב המפתחים, האדמינים ומשתמשי הקצה משתמשים בו. לכן, אפשר להגדיר את התיעוד כגורם מרכזי בסביבה העסקית של WordPress. התיעוד הנוכחי של WordPress לא כולל קבוצה אוניברסלית ומאוחדת של כללים וכללי סגנון לפרסום. מטרת ההצעה הזו היא ליצור קבוצה מלאה ורעננה של הנחיות לגבי סגנון התיעוד, שחלות באופן אוניברסלי על התיעוד של WordPress. רעיון הפרויקט כולל איחוד כל ההיבטים של הנחיות העיצוב והסגנון כמו סמנטיקה, תחביר, הנחיות דקדוק, פיסוק, כללים ספציפיים לפיתוח, מאפייני עיצוב ומפרטי עיצוב. הוא משלב גם מוסכמות שפה כמו קול, טון, מתח, כל חלקי הדיבור, וגם מוסכמות מתן שמות. הכלים, השפות והפלטפורמות שבהם נעשה שימוש יהיו WordPress CMS, GitHub, Markdown ועשויים לכלול גם PHP/MySQL, HTML/CSS ו-JavaScript.
תוכנית הפרויקט:
המצב הנוכחי של מדריכי הסגנון של מסמכי העזרה של WordPress: צוות מסמכי העזרה של WordPress הטמיע שיטת פרסום לא מוצהרת אבל פה אחד של הנחיות. אבל מדי פעם, חלק מהאלמנטים מוגדרים מראש והתהליך הופך לספקולטיבי. אין תקן וקריטריון קבועים לצורך כתיבת ופרסום מאמרים ב-WordPress. צוות התעודה כתב הנחיות סגנון ספציפיות לפרויקטים, אבל אין הנחיות שחלות באופן אוניברסלי. רוב ההנחיות הקיימות לגבי סגנון לא מקובצות במדריך אחד, או שהן הוצאו משימוש וצריך לעדכן אותן. לכן, יש צורך לתכנן ולפתח מדריך סגנון מאוחד כדי לסטנדרטיזציה של מסמכי התיעוד של WordPress.
היעדים:
יותר מ-35% מהאתרים באינטרנט פועלים על WordPress, מה שמצביע על כך שמיליונים של מפתחים ומשתמשי קצה משתמשים בפונקציות המרשימות של WordPress. תיעוד הוא מרכיב חיוני כדי לעזור למפתחים ולמשתמשים האלה למלא ביעילות את הפונקציות האלה ללא טרחה, גם במקרים של אי נוחות. המטרה הכוללת של הצעת הפרויקט הזו היא ליצור סטנדרטיזציה של מדריך עיצוב וסגנון, לאחד מדריכי סגנון קיימים ולעדכן אותם וגם להוסיף תקנות ומפרטים חדשים למסמכי התיעוד של WordPress. כך נוכל להבטיח שימוש קל, פשוט ועקבי במסמכי העזרה של WordPress.
הטמעה:
כפי שהציע המנטור (Jon Ang) של הפרויקט הזה, אפשר לחלק את הפרויקט ל-4 שלבים: שלב גילוי, שלב הגדרה, שלב הטמעה ושלב תחזוקה. לפני תחילת הפרויקט, במהלך התקופה שלפני התמחות, אעבוד עם המנטור שלי ואאשר לוח זמנים מתאים בהתאם ללוחות הזמנים והתוצרים שלי. אני אכיר טוב יותר את מערכת WordPress ואת פרוטוקולי העבודה של הפרויקט הזה.
לקראת תחילת ההתמחות, אני אדבר על תקציר התוכנית ואנסה לנסח את תקציר התוכנית עם החונך שלי. הדרישות והצרכים ייקבעו. קודם אציג את התהליך של יצירת המסמכים ואת תהליך האינטראקציה עם המשתמשים. לאחר מכן, יוצגו קווים כלליים של פריסת כל קטע, קטגוריה ורכיב. לאחר מכן, המנטור שלי יבדוק את הפריסות האלה. אם יהיה צורך, העיצוב של הפריסות ישתנה וחלק מהרכיבים יתווספו או יוסרו. לאחר מכן אערוך מחקר משתמשים כדי לקבוע את השימושיות וההיתכנות של זרימת הממשק. לאחר מכן, 'מדריך הסגנון לתיעוד' ימומש (כפי שמתואר בתרשים שבהמשך) לכל קטע. אפשר גם להפנות למדריכי סגנון של ארגונים אחרים שפועלים במסגרת רישיונות קוד פתוח או רישיונות Creative Commons, כדי להוסיף אותם למדריך שלנו. אם במהלך התקופה הזו יצוצו קשיים בנוחות השימוש, אעצב אותם מחדש.
הבדיקות והאופטימיזציות יתבצעו אחרי שהמדריך לעיצוב יושלם ויושלב ב-HelpHub. נתקן נקודות חולשה, רכיבים או רכיבים יתירים. נבצע בדיקות של ממשק המשתמש והקוד, ונתקן באגים ושגיאות לא רצויות, אם יהיה צורך. תתבצע בקרת איכות סופית של מדריך הסגנון המלא, שתכלול בדיקה של השפה, הדקדוק, האיות, סימני הפיסוק וכו'.
משימות בהמתנה עקב עיכובים בלתי צפויים יושלמו במהלך תקופת המעבר. אפשר להטמיע פונקציות או תכונות נוספות שייקבעו כאפשריות במהלך הפרויקט, אחרי השלמת הבדיקה הסופית. המערכת תבנה תוכנית פריסה והמוצר המוגמר יישלח.
כלים ומתודולוגיות:
התיעוד יקובץ ויערך בפלטפורמה משותפת, כמו Google Docs. אם אתם צריכים לפרסם דרך GitHub, תוכלו להטמיע גם שפות סימון כמו Markdown או GitHub Flavored Markdown. לגבי תקני עיצוב וסגנון, אפשר גם להיעזר בהנחיות סגנוניות בקוד פתוח. לבסוף, המסמך המלא יותאם לפורמט ויפורסם באמצעות WordPress.
טבלת הרכיבים:
זוהי רשימה מקיפה של רכיבים שאפשר להטמיע במדריך הסגנון. הנחיות למסמכים – נגישות, מבנה המסמך, קידוד, מקורות חיצוניים, עובדות, גופנים, קהל גלובלי, שילוב, חוקיות, נגישות בפלטפורמות מרובות, כתיבה לא מעורפלת, בלי הצהרות מוגזמות, פריסת דפים, תקינות פוליטית, פרוטוקולים, אבטחה, מבנה משפטים, כתיבה תמציתית, סגנון וטון, ללא הטיה
שפה ודקדוק - קיצורים וראשי תיבות, אמירה ושליליות, מאמרים, שימוש באותיות רישיות, סעיף, דיבור ישיר/עקיף, אדם ראשון/שני/שלישי, מגדרים, מילון מונחים, שמות עצם, קידומות וסיומות, מינוח, לשון פנייה, התייחסויות, סלנג, לשון פנייה, איות, סלנג וז'רגון, איות
סימני פיסוק – סימן נטוי וסלסול, פסיק נקודה פסיק, פסיק, נקודה, סימן שאלה, מקף נטוי, סוגריים, נקודות, סימן קריאה, מקף נטוי נטוי
עיצוב – תקצירים, מבוא, קטעי מבוא, שמות מותגים, שמות מוצרים, כתוביות, קטעי קוד, בלוקים של קוד, תאריך ושעה, אזורי זמן, מקומות, מטבעות, שמות קבצים, הערות שוליים, כותרות, הדגשה (מודגש, נטוי, קו תחתון, קו חוצה, ציטוט), הכנסה פנימה, אינדקס, קישורים וכתובות URL, רשימות, נקודות חשובות, מספרה, מדיה (תמונות, סרטונים) ואיורים, הערות, אזהרות, טיפים, מספרים ומספרי טלפון, שפות רבות, תרגום, סקריפטים של שפות, רווחים, טבלאות, טקסט, סימנים מסחריים, זכויות יוצרים, פטנטים, הפניות, מדריכים ותהליכים, רכיבי ממשק משתמש, יחידות מידה
ממשק משתמש – פעילויות, לחצנים, קטעי קוד, בלוקים של קוד, ממשק שורת פקודה, תיבת דו-שיח, תפריטים ותפריטים נפתחים, חלונות קופצים והתראות, כרטיסיות, מונחים, רכיבי ממשק משתמש, חלונות
קוד – CSS, HTML, JS, Markdown, MySQL, PHP, תחביר, XML
מילון/מילון מונחים של שימוש במילים – א' עד ת'