סוסי בעד תיעוד! My Horse for a document!

את הממלכה, אחרי הכל, כבר החלפנו בסוס. 

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

כמה תובנות שעלו לי במהלך החיפושים - 

• בדיקות יחידה הן דוגמאות סבירות למדי לשימוש בקוד. זה לא יעיל כמו מסמך שמסביר איך להפעיל דברים, אבל לפעמים אפשר לקרוא את זה וללמוד מה שצריך. 
• בחייאת ראבאק, כתבו הערות. לא בכל מקום (כי אז זה סלט), אבל בראש קבצים שמבצעים משהו שהוא יותר מאשר לוגיקה טריוויאלית, כתבו משהו קצר שמסביר מה מטרת המחלקה\קובץ.  באופן דומה, אם כתבתם ממשק שאחרים יכולים לממש, כתבו שורה או שתיים על מה כל פונקציה צריכה לעשות. זה גם מקום נהדר להסביר לא רק "מה" עושה הקוד, אלא גם "למה". 
• יכולת גילוי, או Discoverability  בלע"ז, זה חשוב לאללה. שימו לב לזה בקוד שלכם, ושל המתכנתים איתם אתם עובדים. 
• תיעוד. תיעוד. תיעוד. טרם פגשתי מישהו שנהנה לכתוב אותו, טרם פגשתי מישהו שלא קיטר לפחות פעם בחייו "למה הם לא כתבו מדריך טוב יותר?". זה כואב, זה לא כיף, וזה נורא לתחזק, אבל לפעמים זה ההבדל בין מוצר שכיף לעבוד איתו לכזה שמתרחקים ממנו כמו מאש. 

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

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

-----------------------------------------------------------------

The kingdom, after all, was already traded for that horse. 

Recently I had the opportunity of playing with several (three) open source(ish) projects. Trying to utilize them. Although the projects are very different in size, purpose, maturity level and community size, one experience was very similar - I knew what I wanted to do. I knew it could be done with the tool, but I spent a whole lot of time trying to figure out the "how" part. Despite the fact that in both cases there was some impressive effort invested into documentation, it just so happened that what I was trying to do somehow wasn't there. With the smaller, less mature project (Allure framework), I ended up cloning the repository and grepping through the source code looking for hints. 

Some insights that I came to while enjoying my wasted time: 

• Unit tests are not really documentation, but they are a semi-decent examples of how to use code. If there isn't anything better, I can try to decipher what I need from them - as long as they are readable. 
• For the love of G*d, write comments. I don't mean commenting the hell out of your code, but a header for every non-trivial class is nice. It's also a great place to write down the "why" part to supplement that "what" part that is in the code.
  Also, if you write an interface that others might implement, please do everyone a favour and write some javadoc above each public method, so that when I come to implement some of it, I can know what I should be doing there. 
• Discoverability is key. It shouldn't be hard to find information about your code, so please pay attention to as many aspects of it as you can - Reasonable naming conventions, clear division of responsibilities, example code, manuals. Heck, even an active user forum might be nice.
• Documentation, documentation, Documentation. I've yet to meet someone that enjoyed writing it, I've yet to meet someone who didn't mutter (or cry out in agony) at least once "why couldn't they write some clear instructions for this?" (Quite often, "they" will be the same team, 6 months ago). Maintaining it is hard, painful and not really fun, but it could be the difference between a product that is pleasant to work with, and something that everyone tries to avoid. 

So, if your team is exposing an API or releasing an SDK - pay double attention to those. You will be saving time to your customers, desperate phone calls to your support team, and you will gain a whole lot of good karma.

Everything is internal? are you building a perfect little closed garden? Cool. You can probably cut some corners. However, do keep in mind that the most important consumer of these discoverability services  - which is future you - will thank you for those little breadcrumbs you leave as you go. 

Or, you could take this approach: 

Your choice.