Fresh Perspective: Specifications

!!!!!!!!!!!!!!!!!!!!!! מזל טוב לתאיר לרגל האירוסין שלה !!!!!!!!!!!!!!!!!!!!!!

Last time I wrote about documentation, I was huffy and annoyed.

Not today.

After posting a link to Joel on Software, I followed my own advice and started reading everything that caught my eye there. And there was a lot that caught my eye.

Notable for today's post are Joel's preachings on functional specifications. Reading them made me think again about what a good spec can do for me, the developer. And my teammates.

The upshot of this is that I am (voluntarily) writing a quick spec of what I expect from a particular functional module in the project. Our original monster document never clarified how the end user will accomplish his goal via interactions with the system. But before we can come out with our long-awaited initial version, we need that clarification. Everyone seems to have a different idea of how the interaction should go, but I think that a good spec would enable us to discuss our ideas in a clear format.

Human Events: A Sequel to Yesterday's Post

After we took two months to generate documentation that was expected in a few weeks, our client seems understandably unwilling to meet with us.

Did we take too long? Of course. Why? Because the work was so difficult for us. Drawing up a large set of statecharts or use-case diagrams is not difficult work, and it's useful in helping the programmer think through the scenarios he needs to handle. Writing up a list of possible screens, possible behaviors, and possible messages is tedious, difficult work to someone who is used to modeling in a graphic language.

What would have happened if we had refused to write such extensive, formal documentation? Could it have been worse than the current situation? Maybe the situation now is salvageable. Maybe then it wouldn't have been? I think we should have negotiated a different form of documentation from the first. Now we're going to have to crawl...

Human Communications

עם כל התיעוד שנאלצנו לכתוב, אני נזכרת בשני ספרים נהדרים:
The Elements of Style
מאת
William Strunk Jr, E.B. White,
The Visual Display of Quantitative Information
מאת
Edward Tufte.
ברצוני לדעת: האם באמת בכל המטרים של ניירת שאנחנו מפיקות יש מידע משמעותי שמגיע לצד השני? האם המסר שלנו ברור? האם אפילו אצלינו הוא ברור?

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

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

כשהשיטה נהיתה כל כך אי-טבעי וכואב, אני משוכנעת שחייב להיות קיים שיטה טובה יותר

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

With all the documentation we're being induced to write, I am reminded of two works: Strunk and White's Elements of Style, and Tufte's Visual Display of Quantitative Information. I wonder, in all the meters of ink on paper we're churning out, how much data is really getting through to the other side. I wonder if our message is clear. I wonder if we even have much message to deliver.

Documentation, we are informed as students, is a necessary part of the software development process where multiple parties with multiple interests and background fields are involved (eg, shareholders and programmers). Proper software development process, they tell us, will help save your project from being so error-prone as to be useless or so far from satisfying your end user as to be rejected.

Is this true? Documentation kept us away from design and code for about two months. This was mostly because drafting documentation to meet the standards set by our client company was completely foreign to our thought patterns. Can this really be the best way to ensure that we're doing it right? At what expense? And considering how far we had to bend our thought patterns to plan and design in this way, how likely is it that we will succeed in actually delivering a product that conforms with what we described?

When the method gets so painfully unnatural, I am convinced that there must be a better way.