דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- WordPress
- כתב טכני:
- טציטוניק
- שם הפרויקט:
- סדרה מלאה ומחודשת של מדריך סגנון למסמכי תיעוד
- אורך הפרויקט:
- תקופה ארוכה (5 חודשים)
תיאור הפרויקט
תקציר:
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, וגם ליצור פשטות ואחידות.
הטמעה:
בהתאם להצעה של המנטור (ג'ון אנג) בפרויקט זה, ניתן לגשת לפרויקט ב-4 שלבים: גילוי, הגדרה, יישום ותחזוקה. לפני תחילת הפרויקט, במהלך התקופה שלפני ההתמחות, אעבוד עם המנטור ואסכם לוח זמנים ולוח זמנים מתאימים בהתאם ללוחות הזמנים ולמוצרים הבאים. אכיר לעומק את מערכת WordPress והפרוטוקולים של העבודה בפרויקט הזה.
עם תחילת ההתמחות, אדון בתקציר התוכנית עם המנטור שלי ואכתוב טיוטה שלו. הדרישות והדרישות ייקבעו. קודם כל, אסביר על זרימת התיעוד ועל תהליך האינטראקציה של המשתמש. לאחר מכן יפורטו המסגרות החוטיות של הפריסה של כל קטע, קטגוריה ורכיב. המדריכים שלי יבדקו את הפריסות האלה. אם יהיה צורך, הפריסות יעוצבו מחדש וחלק מהרכיבים יתווספו או יוסרו. לאחר מכן אבצע מחקר על התנהגות המשתמשים כדי לבדוק את נוחות השימוש וההיתכנות של הזרימה בממשק. לאחר מכן, יוטמע מדריך הסגנון לתיעוד (כפי שמודגם בתרשים שבהמשך) בכל קטע. ניתן להפנות למדריכי סגנון מארגונים אחרים על פי רישיונות קוד פתוח או Creative Commons כדי להוסיף גם את המדריך שלנו. אם במהלך התקופה הזו יהיו קשיים בנוחות השימוש, אתכנן אותם מחדש.
הבדיקות והאופטימיזציות יתבצעו אחרי שמדריך הסגנון יושלם וישולב עם HelpHub. כל נקודות החולשה, הרכיבים או הרכיבים המיותרים יתוקנו. תתבצע בדיקה של הממשק והקוד. אם צריך, באגים לא רצויים ושגיאות יתוקנו. בקרת האיכות הסופית של מדריך הסגנון המלא תבוצע ברמת השפה, הדקדוק, האיות, הפיסוק וכו'.
משימות בהמתנה עקב עיכובים בלתי צפויים יושלמו בתקופת האחסון הזמני. לאחר סיום הבדיקה הסופית, ניתן להטמיע פונקציונליות או תכונות נוספות שיהיו ניתנות לביצוע במהלך הפרויקט. המערכת תבנה תוכנית פריסה והמוצר המוגמר יישלח.
כלים ומתודולוגיות:
המסמכים יקובצו וייערכו בפלטפורמה משותפת כמו Google Docs. אם צריך לפרסם דרך GitHub, אפשר להטמיע גם שפות סימון כמו Markdown או GitHub Flavored Markdown. ניתן להפנות גם להנחיות סגנון של קוד פתוח לתקנים של עיצוב וסגנון. לבסוף, המסמך המלא יעוצב ויפורסם באמצעות WordPress.
טבלת רכיבים:
זוהי רשימה מקיפה של הרכיבים שניתן להטמיע במדריך הסגנון. הנחיות למסמכים – נגישות, מבנה מסמכים, קידוד, מקורות חיצוניים, עובדות, גופנים, קהל גלובלי, קבלת האחר, חוקיות, נגישות בפלטפורמות מרובות, לא דו-משמעית, ללא טענות מוגזמות, פריסת דף, תיקון פוליטי, פרוטוקולים, אבטחה, מבנה משפטים, כתיבה תמציתית, טון וסגנון, ללא הטיה
שפה ודקדוק - קיצורים וראשי תיבות, אמירה ושליליות, מאמרים, שימוש באותיות רישיות, סעיף, דיבור ישיר/עקיף, אדם ראשון/שלישי, מגדרים, מילון מונחים, שמות עצם, תחיליות וסיומות, מילות יחס, לשון פנייה, אזכור, סלנג וז'רגון, מונחים טכניים, סלנג וז'רגון, מונחים טכניים, מונחים טכניים.
פיסוק - גרש ומירכאות, נקודתיים ונקודה-למחצה, פסיק, שלוש נקודות, סימני קריאה, מקפים ומקפים, סוגריים, נקודות, סימני שאלה, קווים נטויים
עיצוב - תקצירים, מבוא, הקדמה, שמות מותגים, שמות מוצרים, כתוביות, קטעי קוד, בלוקי קוד, תאריך ושעה, אזורי זמן, מקומות, מטבעות, שמות קבצים, הערות שוליים, כותרות וכותרות, הדגשה (מודגש, נטוי, קו תחתון, קו חוצה, מירכאות), מספר כניסה, אינדקס, קישורים וכתובות URL, תבליטים, מטבעות
ממשק משתמש – פעילויות, לחצנים, קטעי קוד, בלוקים קוד, ממשק שורת הפקודה, תיבות דו-שיח, תפריטים ותפריטים נפתחים, חלונות קופצים והתראות, כרטיסיות, מונחים, רכיבי ממשק משתמש, Windows
קוד - CSS, HTML, JS, Markdown, MySQL, PHP, תחביר, XML
מילון/מילון מונחים בנושא שימוש במילים – A עד Z