שיטות עבודה טובות לפיתוח תוכנה חופשית ופתוחה: תיעוד

תיעוד: שיטות עבודה טובות לפיתוח תוכנה חופשית ופתוחה

תיעוד: שיטות עבודה טובות לפיתוח תוכנה חופשית ופתוחה

La תיעוד הוא וצריך להיות חלק מהותי מה- תהליך יצירה ותכנון מכל הפעילות האנושית, ועוד בתחום הטכנולוגי, במיוחד בתחום פיתוח תוכנה.

El מטרת כל התיעוד זה בטח הוא ללמד צדדים שלישיים (משתמשים, מנהלים, מתחזקים או מפתחים אחרים), שבדרך כלל לא מכירים את מוצר (קוד, יישום או מערכת), איך זה נוצר המבנה שלו, הפעולה שלו וגם אם אפשר, הסיבה ליצירתו ודרך העיצוב וההפעלה שלו.

שיטות עבודה טובות: תיעוד - מבוא

יתר על כן, במקרה הספציפי של תיעוד תוכנה חופשית הוא חיוני, מכיוון שהוא מאפשר להבטיח באופן מלא את העברת ידע והעצמה הכרחי להגשמה מספקת של 4 חירויות מקודמים על ידי זה, שהם:

  • 0: החופש להפעיל את התוכנית ככל שתרצה, לכל מטרה שהיא.
  • 1: החופש לגשת לתכנית וללמוד אותה ולשנות אותה או להתאים אותה לטובתך.
  • 2: החופש לשתף או להפיץ מחדש עותקים כדי להפיץ אותו ו / או לעזור לאחרים.
  • 3: החופש להפיץ עותקים של הגרסאות שהשתנו לצדדים שלישיים.

תיעוד טוב מאפשר לכן, שהמוצר שנוצר:

  • משתמשים בו נכון, והוא נלמד ונלמד ביתר קלות.
  • להיות מובן היטב על ידי מי שרוצה לשנות אותו כדי לשפר או להתאים אותו.
  • היו משותפים ומתקבלים בביטחון רב יותר, בין כל המכרים והזרים הפוטנציאליים.
  • שיהיה לך מסה טובה יותר בקרב הציבור.

שיטות עבודה טובות: תיעוד - Readme

שיטות עבודה טובות: תיעוד

יסודות

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

לא יוצרים תיעוד טוב כשמדובר לפתח תוכנה חופשית, קוד פתוח או כל סוג אחר של תוכנה, הוא לשלוח לנמענים האפשריים שלה (משתמשים, מנהלי מערכת, אנשי תחזוקה או מפתחים אחרים) למצוא דרך בג'ונגל ללא מפה או מצפן.

צור תיעוד טוב לכל אחד תוכנה חופשית, קוד פתוח זה גם מועיל, שכן, אם כי לתיעוד יש עלותההשקעה, אם נעשית נכון, שווה את זה. כי, העולם של תוכנה מלא בסיפורים על קודים מדור קודם תוכניות, יישומים או מערכות ישנות או עדכניות, שרק מעטים האנשים שמעזים לגעת בהם, כי כמעט אף אחד לא מבין. מתכנתים מתמקדים ביצירת קוד ולא בתיעודו בצורה נכונה ומלאה. ויש לתקן זאת.

שיטות עבודה טובות לתיעוד בקבצי טקסט README

במקרה של תוכנה חופשית וקוד פתוח, תיעוד מוגבל לרוב לקבצי טקסט, כאשר הוא נוצר על ידי אנשים או קבוצות קטנות של מתכנתים או קהילות. אבל, עד ליצירת תיעוד פשוט באמצעות פשוט קובץ טקסט README.md (או .txt) אתה יכול לקבל את שלך שיטות עבודה מומלצות או טובות, טיפים או מדריך שימושי ליצירה כדי להביא לצדדים שלישיים את המידע המלא והמפורט ביותר הדרוש אודות הנוצר.

עבור המאמר שלנו, לקחנו את שיטות עבודה טובות נתפס ונחשף על ידי "קוד לפיתוח יוזמה" דל הבנק לפיתוח Interamerican, אשר לסיכום אומר לנו שתיעוד טוב המבוסס על א קובץ טקסט README.md (או .txt) עליו להיות מובנה באופן הבא:

מבנה קבצים מומלץ של README

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

אלה תרגול טוב, הם ממליצים להוסיף גם ל- תיעוד קבצי README כדי להפוך את זה למלא יותר, הסעיפים הבאים:

  • כיצד לתרום: סעיף המסביר למפתחים חדשים את התהליך לתרומה לפרויקטים.
  • קוד התנהגות: סעיף המסביר את קוד ההתנהגות קובע את הנורמות, הכללים והאחריות החברתיים שעליהם אנשים וארגונים צריכים לעקוב כאשר הם מתקשרים בצורה כלשהי עם הכלי הדיגיטלי או עם הקהילה שלהם.
  • תגים: קטע המציג את התגים (תמונות קטנות המוטמעות ב- README.md) המציינות בצורה קריאה ותמציתית את מצב הכלי.
  • גִרְסָה: קטע המציין רשימה של גרסאות הכלי הדיגיטלי והפונקציות שנוספו לכל גרסה.
  • תודות: סעיף המכיל את ההכרות לאנשים או ארגונים אחרים שתרמו בדרך כלשהי לפרויקט.

כדי להרחיב מידע זה, על שיטות עבודה טובות בענייני תיעוד לפיתוח תוכנה חינם, דרך "קוד לפיתוח יוזמה" דל הבנק לפיתוח Interamerican תוכלו ללחוץ על הקישור הבא: תיעוד - מדריך לפרסום כלים דיגיטליים. ובפרסומים אחרים נחקור את החלק המתייחס אליו תרגול טוב על הערכה ורישוי דל תוכנה חופשית ופתוחה עצמם.

מסקנה

מסקנה

אנחנו מקווים ש זה "פוסט קטן ומועיל" על «Buenas prácticas» בשדה של «documentación» ליצור בעת פיתוח «Software libre y abierto», יהיו בעלי עניין ותועלת רבה לכל אורך הדרך «Comunidad de Software Libre y Código Abierto» ובעל תרומה רבה להפצה של המערכת האקולוגית הנפלאה, הענקית והצומחת של יישומים של ועבור «GNU/Linux».

ולמידע נוסף, תמיד אל תהססו לבקר באף אחד ספרייה מקוונת כמו OpenLibra y ג'דיט לקרוא ספרים (קובצי PDF) בנושא זה או אחרים תחומי ידע. לעת עתה, אם אהבת את זה «publicación», אל תפסיקו לשתף אותו עם אחרים, שלך אתרים, ערוצים, קבוצות או קהילות אהובים של רשתות חברתיות, רצוי בחינם ופתוחות כ- מסטודון, או כמו מאובטח ופרטי מברק.

או פשוט בקר בדף הבית שלנו בכתובת DesdeLinux או להצטרף לערוץ הרשמי מברק של DesdeLinux לקרוא ולהצביע לפרסומים מעניינים אלה או אחרים «Software Libre», «Código Abierto», «GNU/Linux» ונושאים אחרים הקשורים ל «Informática y la Computación», ו «Actualidad tecnológica».


היה הראשון להגיב

השאירו את התגובה שלכם

כתובת הדוא"ל שלך לא תפורסם. שדות חובה מסומנים *

*

*

  1. אחראי לנתונים: מיגל אנחל גטון
  2. מטרת הנתונים: בקרת ספאם, ניהול תגובות.
  3. לגיטימציה: הסכמתך
  4. מסירת הנתונים: הנתונים לא יועברו לצדדים שלישיים אלא בהתחייבות חוקית.
  5. אחסון נתונים: מסד נתונים המתארח על ידי Occentus Networks (EU)
  6. זכויות: בכל עת תוכל להגביל, לשחזר ולמחוק את המידע שלך.