מפתח עוזב, והבא אחריו מבלה שלושה שבועות בהבנת האופן שבו פועל רכיב סינכרון 1C מותאם אישית. עדכון ליבת Bitrix שובר מודול מותאם אישית כי אף אחד לא תיעד אילו hooks הוא משתמש. אין תיעוד פירושו אין יכולת העברה: כל צוות מתחיל מאפס.
בפרויקטי Bitrix, המצב מסתבך בשל שילוב של הליבה הישנה, ה-API של D7 ומודולים מותאמים אישית — ללא תיאור, לא ברור אפילו היכן הדברים ממוקמים. אנו נתקלים בפרויקטים כאלה באופן קבוע ויודעים כיצד לסדר את הכאוס.
למה תיעוד קריטי לפרויקטי Bitrix
ללא תיעוד, כל מפתח חדש מבלה לפחות 40 שעות בהבנת הקוד. ביקורת של פרויקט Bitrix טיפוסי מראה של-60% מהקוד המותאם אישית אין הערות. זה משלש את הזמן לתיקון באגים בהשוואה לפרויקט מתועד. תיעוד הוא השקעה שמחזירה את עצמה בעדכון הקרנל הראשון או בתחלופת מפתחים. פרויקט עם תיעוד ב-Git/docs/ מתעדכן פי שניים מהר יותר מפרויקט עם הערות מפוזרות.
מה אנו מתעדים בפרויקט Bitrix
להלן בלוקי המפתח שיש לתאר:
- ארכיטקטורת הפרויקט: מבנה התיקיות תחת /local/, מודולים מותאמים אישית ב-/local/modules/, תבניות אתר, מהדורות וגרסאות בשימוש (Bitrix, PHP, DBMS, OS), תרשים תשתית שרת, רשימת ספריות צד שלישי (Composer, npm).
- מודולים ורכיבים: מטרה, מתודות ציבוריות, ווי אירועים בשימוש, תלויות, טבלאות מסד נתונים. נדרש עם בלוקי PHPDoc.
- אינטגרציות: מנגנון (API, CommerceML, webhooks), פרמטרי חיבור, לוח זמנים, נוהל שחזור.
- פריסה ותחזוקה: פריסה שלב אחר שלב על שרת נקי, נוהל עדכון ליבה, נוהל החזרה לאחור.
השוואה בין פורמטים של תיעוד
| פורמט | יתרונות | חסרונות |
|---|---|---|
| README.md במאגר | ניהול גרסאות, נגישות, עריכה קלה | עיצוב מוגבל, לא מתאים לנפח גדול |
| Confluence / Notion | עיצוב עשיר, צילומי מסך, חיפוש, שיתוף פעולה בצוות | דורש סנכרון עם הקוד, תלות בענן |
| OpenAPI 3.0 | יצירה אוטומטית של לקוחות, תקן בתעשייה | מורכבות עבור API פנימיים ופתרונות לא סטנדרטיים |
אנו ממליצים לשלב גישות: README ראשי במאגר ותיעוד מפורט ב-Confluence לעבודה בצוות ולעדכונים.
מבנה אופייני של README.md
| סעיף | תוכן |
|---|---|
| תיאור | סקירה קצרה של הפרויקט, הבעיות שנפתרות |
| דרישות | PHP, תוספים, DBMS, גרסאות (פרטים בתיעוד Bitrix) |
| התקנה | הוראות שלב אחר שלב |
| מבנה הפרויקט | קישורים לתת-ספריות ולמודולים |
| מקורות | תיעוד מפורט ואנשי קשר |
דוגמה ל-PHPDoc עבור מודול מותאם אישית
/**
* Resolves an article into a SKU ID.
*
* @param string $article Product article (property PROPERTY_CML2_ARTICLE)
* @param int $iblockId Information block ID for SKUs
* @return int|null Offer ID or null if not found
*
* @throws \Bitrix\Main\ArgumentException For invalid iblockId
*/
public function resolveArticle(string $article, int $iblockId): ?int
עבור פתרונות לא סטנדרטיים — הערות inline על ה'למה', ולא על ה'מה':
// Using SELECT FOR UPDATE here instead of ORM because
// DataManager does not support locking reads in the current Bitrix version
אנו מקפידים על הסטנדרטים של תיעוד 1C-Bitrix הרשמי עבור PHPDoc. בפועל, פרויקטים ללא תיעוד קשים יותר לתמיכה טכנית ומתפקדים לאט יותר. מפתחים חדשים מאבדים 30-40% מהפרודוקטיביות שלהם בחודש הראשון בגלל הצורך לפענח קוד באופן עיוור. תיעוד נכון מקצר תקופה זו בחצי ומאפשר לעובדים חדשים לתרום באופן מלא מהשבוע הראשון.
כיצד אנו מבטיחים שהתיעוד נשאר מעודכן
רלוונטיות היא האתגר הגדול ביותר של תיעוד. הפתרון שלנו: תיעוד הופך לחלק מ-Definition of Done. משימה אינה נסגרת עד שדף התיעוד המתאים מתעדכן. בנוסף, אנו מבצעים ביקורות תיעוד קבועות כל שלושה חודשים.
בפועל, כל מפתח משקיע 30 דקות בתיעוד השינויים שלו, אך חוסך שבועות כאשר חברי צוות חדשים נקלטים. זוהי השקעה בעתיד הפרויקט, במיוחד קריטית עבור עדכוני Bitrix מתוכננים.
מה כלול בשירות
- ביקורת של תיעוד קיים וזיהוי פערים
- כתיבת תיאור ארכיטקטוני של הפרויקט (מבנה, מודולים, אינטגרציות)
- תיעוד מודולים מותאמים אישית ורכיבים לא סטנדרטיים
- תיאור כל האינטגרציות עם פרמטרים ונהלי שחזור
- הוראות פריסה ותחזוקה
- מדריך משתמש לפאנל הניהול
כיצד אנו עובדים
תהליך התיעוד מתחיל בביקורת מפורטת של הקוד והתשתית הנוכחיים. אנו מראיינים מפתחים מרכזיים, אוספים מידע על event hooks, מודולים ולוגיקה מותאמת אישית. לאחר מכן אנו מארגנים את החומר לפורמט נוח ויוצרים תבניות לשמירה על רלוונטיות. בפועל, פרויקטים עם תיעוד טוב דורשים 50% פחות זמן לתיקון באגים ועדכונים.
עלות השירות מחושבת באופן אישי על בסיס ביקורת מקדימה. אנו מעריכים את היקף התיעוד ולוח הזמנים בתוך יום אחד. צרו קשר לייעוץ. הזמינו ביקורת של התיעוד הנוכחי שלכם — נזהה פערים ונציע תוכנית.