סוסי בעד תיעוד! 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. 

Beating robots down with your bare hands: Quality

Reading Time: 8 minutesI’ve recently had a conversation with Maaret Pyhäjärvi related to a topic I’ve submitted to Eurotest Conf, it was about AI and humans, and quality of testing and all that hype around us loosing our jobs to machines. Well, the talk didn’t quite make it to the conference schedule, but it was great I had the opportunity to speak with Maaret at first and talking with her actually gave me some interesting ideas to think of. So, thanks for that, Maaret! […]

The post Beating robots down with your bare hands: Quality appeared first on Mr.Slavchev.

A Different Class

In Stop Working & Start Thinking (which I also mentioned the other day)  Jack Cohen and Graham Medley want scientists to consider what science is and how they do it, as well as just getting on with it. To help explain this, they partition scientific answer-seeking like so:

  • observation
  • measurement
  • investigation
  • experiment

And that’s interesting in and of itself.  But the authors have been round the block and so recognise that this categorisation is not absolute, and that sometimes it might not be clear where a particular activity sits, and that some activities probably sit in multiple categories at different times and even at the same time.

In science — and thinking, so this applies to you too, testers — generalisations are useful because they help us to frame hypotheses at relevant granularities. We’re all made up of atoms but a description of social deprivation in inner cities at an atomic level would unhelpfully obscure, for example, that higher-level concepts such as social class can be useful factors in such an analysis. Further, this can be true despite social class itself being a fluid notion.

But generalisations are problematic for scientists — and thinkers, which includes us testers. It’s easy to be lulled into a false sense of security when, for example, all known observations show one general thing (swans are white) but then a new observation doesn’t fit (it looks just like a swan, but it’s black). There’s a human tendency to want to avoid complicating a simple model, and so reject the data (that’s not a swan!) which doesn’t improve the theory.

Scientists, Cohen and Medley say — and I’d add testers also — should retain a critical distance when classifying: what does it mean to be a black swan? Would, say, a white stripe under one wing affect this? Could there be shades of black? Could there be greys? What explanatory power does a given classification permit? What does it prevent?

Further, they add, involving tools in categorisation, or more generally in any measurement, requires another consideration:

… when measurement is automated, the final figure, the one you get from the machine, incorporates the prejudice of the designer, not yours!

Class.
Image: https://flic.kr/p/pEuUf8

Getting Ready to CAST a Wide Net in Nashville

It’s time to get back in the saddle and start doing some live blogging and somewhat real-time podcasting. Now that CAST is this week in Nashville, I’m doing my last bit of planning and logistics to get me to Nashville and get ready for CAST. For the past couple of months, Claire Moss and I have done some teaser podcasts for the conference (dubbed the AST CASTcast). If you haven’t been following along, here’s the whole series we’ve produced thus far (we have 18 episodes you can listen to 🙂 ):

I will be Live Blogging this conference, but in a change from the past, I will not be doing it here on Testhead. AST has asked me to do my Live Blogging directly with the conference materials, so I encourage everyone to follow along over at the AST site.

With that in mind, I’d like to do an experiment. There are many sessions I would like to attend, but since I’m live blogging the event, I thought I would throw out to the readers of Testhead… what talks would you like to have me attend? What topics interest you? What do you think I might benefit from tuning into that may not currently be on my radar?

Also, I will be packing my microphone, so if you would like to have us record a podcast or two while we are there, let me know who you would like to interview and we can see if they would be game to participate.

It’s going to be an active week. I hope you all will follow along with me, and yes, I will also post some here as well :).