[OT] I got a JOB!!!

On Wed, 17 May 2017 18:07:14 +0300, Niklas Holsti
<niklas.holsti@tidorum.invalid> wrote:

>On 17-05-17 13:54 , Don Y wrote:
>> On 5/17/2017 3:12 AM, Reinhardt Behm wrote:
>>>  [snips]
>>> But I must confess I sometimes do something like this: When the customer
>>> does not really know what he wants or I myself need to get a feeling
>>> how a useful user interface should be. Then I do prototyping this way.
>>> Later the sys-reqs are derived from these prototypes and the software
>>> is developed again according to these reqs. The prototyping-code goes
>>> into a CVS-branch called "playground".
>>
>> I write user manuals, now, instead of specifications.  They have to address
>> all of the same information that is presented in a specification -- cuz the
>> user needs to know why/when this "error" will be thrown, or that constraint
>> imposed, etc.
>
>For my last product, I wrote a combined user manual and requirement 
>specification, using LibreOffice conditional text: set a document 
>variable one way, it is a user manual; set the variable differently, and 
>every meaningful paragraph gets a requirement number that can be 
>referenced in tests and validation matrices.
>
>Only drawback is that the paragraphs are rather shorter than in usual prose.
>
>Of course this document expresses only high-level, user-level 
>requirements. The same approach would not work for low-level, technical 
>requirements, I think.


FWIW, for many years (and perhaps still today), IBM did just that with
the ISA specification for S/360 and its descendents (The "Principles
of Operation" manual).  The internal version has considerably more
detail about corner cases, implementation issues, design choices, use
cases, the actual handing of architecturally undefined items, etc. But
both the internal and external versions were (are?) produced off a
common, marked-up, source document.

On 5/17/2017 6:57 AM, Reinhardt Behm wrote:
>> Instead of having to actually *build*/prototype it and hope they
>> stumble on those same problems by "poking REAL buttons" (instead
>> of hypothetical buttons)
>
> No problem with this. The sys-reqs should just convey what the system does
> or should do. Your method of writing a "user manual" makes a some sense to
> me. As you rite it might help to find problems in the reqs. Thus help to
> create correct reqs.

Being conversational/narrative instead of declarative *seems* to be easier
for folks (e.g., clients) to relate to the content.  Listing a set of
"dry" requirements, free of context, seems to strain most folks' imaginations
("How does this pertain to <whatever>?").

Illustrations and a foamcore/cardboard/wood mockup (e.g., so they can see the
keys on a keypad, get an idea where the whizzbanger is located in relation to
that -- "Gee, how will left-handed folks feel using this?" -- and start
IMAGINING a real unit without requiring all the effort to fabricate the
electronics, software, etc.).

IME, any effort put into slapping together a "talking demo" (Dog 'n' Pony)
is hard to *discard*; there's always the nagging thought that you could
SALVAGE that effort and be a bit closer to "done".

But, you've probably not fully documented nor tested that stuff as it
wasn't expected to be ready for prime time.  And, you'll be biased
in your attempts to document/test it now -- opting to describe "what you
see" (or want to see) and not what it *should* have been, had you done
it AFTER knowing what your ultimate goal would be.

> My main point is that there should be a clearly defined spec for the system.

Preaching to the choir...

> Whether this is prose or what you call legalese is not so important. The

I understand your point, but I actually do think there is a big difference!
I used to write very detailed, "technical" specifications in "legalese"...
defining each term, formally, before use; highlighting each instance of
it in the text to draw attention to its role as a "Proper Noun" (so to speak);
etc.

I found that people found these too dry (IBM/Xerox-ish) and couldn't relate
the "requirement" to the likely implementation that would ultimately follow.
The User Manual approach is deliberately more colloquial and directly pertinent
to the final (yet to be produced) product.

I.e., when it talks about how the device will react to "incorrect user actions"
(lets not call them "user errors"), there is a narrative that puts those
actions in a context:  "Ah, OK; I can see how someone might do this out of
order..."

And, as I would ultimately end up having to create such a document, it
gives me that document "free" (at the expense of the "specification";
but, the folks that would normally see the specification see it in this
disguised -- but EQUIVALENT -- form).  I am loathe to have a single
datum (the "specification") present in two different forms -- it opens
the door for the two to disagree or for one to be updated without the
changes reflected in the other, etc.

> spec I write are also more prose than legalese. But I need something that I
> can also easily use to develop test cases from. I am not sure how to easily
> do that and be sure to have covered everything. It could make a gap analysis
> more complicated.

Yes.  But, easier for *you* to take on some "heavy lifting" than to pass
that extra effort on to others -- who may not be as disciplined!

(Life's not fair  :> )

On 5/17/2017 8:07 AM, Niklas Holsti wrote:
> On 17-05-17 13:54 , Don Y wrote:
>> On 5/17/2017 3:12 AM, Reinhardt Behm wrote:
>>>  [snips]
>>> But I must confess I sometimes do something like this: When the customer
>>> does not really know what he wants or I myself need to get a feeling
>>> how a useful user interface should be. Then I do prototyping this way.
>>> Later the sys-reqs are derived from these prototypes and the software
>>> is developed again according to these reqs. The prototyping-code goes
>>> into a CVS-branch called "playground".
>>
>> I write user manuals, now, instead of specifications.  They have to address
>> all of the same information that is presented in a specification -- cuz the
>> user needs to know why/when this "error" will be thrown, or that constraint
>> imposed, etc.
>
> For my last product, I wrote a combined user manual and requirement
> specification, using LibreOffice conditional text: set a document variable one
> way, it is a user manual; set the variable differently, and every meaningful
> paragraph gets a requirement number that can be referenced in tests and
> validation matrices.
>
> Only drawback is that the paragraphs are rather shorter than in usual prose.

The problem, here, is that you have the same "data" represented in two
different forms (views/documents).  So, there is the implicit concern
that the two may be -- or become -- out of sync.  Like comments in code
not agreeing with what the code is NOW doing (after some revision).

I think verifying the two are in agreement is a harder task requiring
more discipline than preparing either document individually.  It's too
tempting to just think (hope!) you've got BOTH documents so "let's move
on"...

> Of course this document expresses only high-level, user-level requirements. The
> same approach would not work for low-level, technical requirements, I think.

It's impractical to write a "manual" for something as fine-grained as a
function -- or the power conditioning circuitry (if hardware-speak) *in*
a design.

OTOH, its not a stretch to write a "manual" (or, "a descriptive text")
for a subsystem.  This allows you to present your design approach,
background information, competing approaches (that you ruled out -- along
with an explanation of "why"), establish a lexicon (that you can then
use without further clarification in your source code, etc.), etc.

E.g., in describing my gesture recognizer, I have an assortment of
largely arbitrary terms to reference various aspects of the dataset
in the algorithm:  points, beziers, curves, paths, segments, gestures,
etc.  As each has a specific use, those uses need to be clarified
so a "segment" isn't referenced when a "path" is intended, etc.

In past projects, I'd include several pages of prose in the source code
explaining what was going to happen in the module(s) that followed.
By pulling this out of the source code file(s), I can now augment it
with illustrations, animations, multimedia, etc.

On 17/05/17 00:32, Tim Wescott wrote:
> On Tue, 16 May 2017 23:51:26 +0100, Tom Gardner wrote:
>
>> On 16/05/17 23:11, Tim Wescott wrote:
>>> On Tue, 16 May 2017 22:05:49 +0100, Tom Gardner wrote:
>>>
>>>> On 16/05/17 21:24, Tim Wescott wrote:
>>>>> On Tue, 16 May 2017 20:17:17 +0000, eric.jacobsen wrote:
>>>>>
>>>>>> On Tue, 16 May 2017 13:49:28 -0500, Tim Wescott
>>>>>> <seemywebsite@myfooter.really> wrote:
>>>>>>
>>>>>>> Since this is a newsgroup, and this is news...
>>>>>>>
>>>>>>> Wescott Design Services is going into remission, while I pursue a
>>>>>>> day job.  Job title is Software Designer 5 at Planar Systems -- so
>>>>>>> any circuit design or control systems jones will have to be
>>>>>>> satisfied by hobby work or on the side.
>>>>>>
>>>>>> Software Designer 5?   Sounds a little like being in Sector 7-G?
>>>>>
>>>>> "Really Senior Embedded Guy".
>>>>>
>>>>>>> In the near term I'll be finishing up current work with current
>>>>>>> customers; in the longer term I'll probably concentrate on the
>>>>>>> educational videos and maybe hobby stuff.
>>>>>>>
>>>>>>> Lots of embedded Linux work in my near future, and possibly TDD
>>>>>>> proselytizing.
>>>>>>
>>>>>> Time Division Duplex?
>>>>>
>>>>> Test Driven Design.
>>>>
>>>> Be prepared to meet some people that believe X works /because/ all the
>>>> unit tests for X are passed and the console shows a green light.
>>>
>>> Well, yes.  The two main good things about TDD for me is that it makes
>>> me think early about how something really should work, and there are
>>> finer- grained tests to make sure that if I did something really
>>> dumbass it gets caught.
>>>
>>> Even with TDD, I still find errors, so I don't live under the delusion
>>> that you can test in quality.
>>>
>>>> Usually they have never been introduced to the concept that "you can't
>>>> test quality into a product".
>>>> Unit tests developed as part of TDD are highly beneficial, but are not
>>>> sufficient.
>>>>
>>>> But I'm sure you know that!
>>>
>>> Yea verily!!
>>
>> The other dysfunctional aspect of unit tests is that,
>> while they are very useful when making incremental improvements during
>> design, they can be a real impediment in a few months/years time. The
>> problem is that over time people forget which tests demonstrate required
>> properties, and which are merely ensuring behaviour of implementation
>> artifacts. At that point people are afraid to make changes that break
>> tests, even if the tests are unimportant. At that point the codebase has
>> become ossified.
>>
>> Classic anti-patterns warning of that: unit tests on getters/setters,
>> and/or changing visibility solely to enable unit tests.
>
> That's an interesting point.  I haven't been using TDD long enough for
> that to be an issue.  Good to know!

Another stumbling block can be to get people to consider
the definition of "unit" in a unit test. Too frequently
they equate it with "unit" = class/method.

Sometimes they have difficulty thinking that unit can be
a subsystem - they think that /can't/ be unit testing
because it is "integration testing".

If they argue, get them to define what they mean by
a "unit test", and then point out that actually their
"unit test" isn't testing a unit. It is testing the
integration of their code and library code (and
compiler and runtime).

The corollary is that TDD mentality and technology
can - and often should - be applied to integration
testing. All you have to do is increase the granularity
of the UUT.

On 17/05/17 15:59, Paul wrote:
> In article <xOUSA.16651$C56.666@fx34.am4>, spamjunk@blueyonder.co.uk
> says...
>>
>> On 17/05/17 10:10, Paul wrote:
>>> In article <B0USA.14491$8r1.938@fx42.am4>, spamjunk@blueyonder.co.uk
>>> says...
>>> .......
>>>> The simple point to bear in mind is that the results of TDD
>>>> are only as good as the quality of the tests. Test the
>>>> wrong/unimportant thing, or don't test important behaviour,
>>>> and the outcome can be "suboptimal".
>>>>
>>>> That's not a difficult point (to put it mildly!), but it
>>>> is horrifying how it is ignored by zealots and/or not
>>>> appreciated by inexperienced.
>>>>
>>>> The best defense is, to quote one of the two mottoes
>>>> worth a damn, "Think". No change there, then!
>>>
>>> The Titanic sank but I bet nearly all the individual parts past their
>>> unit tests.
>>>
>>> Or the video I saw on Dev Humor a while back of sliding door and bolt
>>> to lock door fixed wrong way. Each part past its unit tests.
>>
>> Yup.
>>
>> None of this is difficult, but it does seem
>> to escape some people :(
>
> Some of the classic videos
>
> http://devhumor.com/media/2-unit-tests-0-integration-tests
>
> and
>
> https://www.youtube.com/watch?v=0GypdsJulKE

:)

Of course there's a good argument that much (most?)
"integration testing" is really just "unit testing"
with larger units.

People can get too stuck on the specific definition
(of unit) they have been taught.

On 17/05/17 16:02, Tim Wescott wrote:
> On Wed, 17 May 2017 09:12:46 -0400, Randy Yates wrote:
>
>> Tim Wescott <seemywebsite@myfooter.really> writes:
>>
>>> Since this is a newsgroup, and this is news...
>>>
>>> Wescott Design Services is going into remission, while I pursue a day
>>> job.  Job title is Software Designer 5 at Planar Systems -- so any
>>> circuit design or control systems jones will have to be satisfied by
>>> hobby work or on the side.
>>>
>>> In the near term I'll be finishing up current work with current
>>> customers; in the longer term I'll probably concentrate on the
>>> educational videos and maybe hobby stuff.
>>>
>>> Lots of embedded Linux work in my near future, and possibly TDD
>>> proselytizing.
>>
>> Congratulations Tim. We'll have to exchange trade secrets someday...
>>
>> BTW, does PS use a specific unit test framework? Have you used it yet?
>> How do you like it?
>
> I start next week, so I don't know and no.  It's my former coworker from
> FLIR who's pushing TDD, and the manager who hired me is kind of warily
> standing on the sidelines going "what's the deal here?"
>
> The guy pushing it is extremely smart and capable, so whatever it is it's
> probably good.

I expect you'll find it is the codification of
many of the development mentality and practices
that you have been using for a long time.

Be cautious about how TDD applies to bottom-up design
(i.e. finding things that work and clagging them
together) v.s. top-down design. TDD works naturally
with top-down design where all the yet-to-be-implemented
are well understood and feasible.

Anybody that /thinks/ will realise that sometimes
it is beneficial to do a "spike investigation" to
quickly validate key concepts from top-to-bottom, and
then to use that experience to do it "properly"
using full-blown TDD.

On 5/17/2017 9:47 AM, Don Y wrote:
> In past projects, I'd include several pages of prose in the source code
> explaining what was going to happen in the module(s) that followed.
> By pulling this out of the source code file(s), I can now augment it
> with illustrations, animations, multimedia, etc.

By way of another example, in the "tutorials" (not a "user manual")
for my speech synthesizers...

When confined to solely ASCII text, one would traditionally use
symbols like AY EY AW IY IH AA etc for "vowel sounds".  And,
without any training, READers (deliberate emphasis) would almost
always mistake the sounds being referenced.

E.g., "AY" does not represent the "long a" sound in "say" but,
rather, the "long i" sound in "ride" (!)

Abandoning ASCII (by NOT including the descriptive text in the
ASCII source code files), I can use the more correct IPA symbol
for the sound (a sort of ligatured "ai" -- which STILL suggests
a "long a" sound to a naive READer).

Further, adopting a document container that lets me include multimedia
in the presentation means I can let a READer become a LISTENer -- and
play a sound clip of the particular sound being indicated by the grapheme.

[If you've lived in different parts of the country (USA), you'd recognize
that you can't just use words as examples of sounds -- the 'a' in "mash"
is pronounced very differently in different parts of the country; the 'y'
in "my" mimics the 'i' sound in "ride" in some places but sounds like
"mah" in others!]

On Wed, 17 May 2017 18:11:22 +0100, Tom Gardner wrote:

> On 17/05/17 16:02, Tim Wescott wrote:
>> On Wed, 17 May 2017 09:12:46 -0400, Randy Yates wrote:
>>
>>> Tim Wescott <seemywebsite@myfooter.really> writes:
>>>
>>>> Since this is a newsgroup, and this is news...
>>>>
>>>> Wescott Design Services is going into remission, while I pursue a day
>>>> job.  Job title is Software Designer 5 at Planar Systems -- so any
>>>> circuit design or control systems jones will have to be satisfied by
>>>> hobby work or on the side.
>>>>
>>>> In the near term I'll be finishing up current work with current
>>>> customers; in the longer term I'll probably concentrate on the
>>>> educational videos and maybe hobby stuff.
>>>>
>>>> Lots of embedded Linux work in my near future, and possibly TDD
>>>> proselytizing.
>>>
>>> Congratulations Tim. We'll have to exchange trade secrets someday...
>>>
>>> BTW, does PS use a specific unit test framework? Have you used it yet?
>>> How do you like it?
>>
>> I start next week, so I don't know and no.  It's my former coworker
>> from FLIR who's pushing TDD, and the manager who hired me is kind of
>> warily standing on the sidelines going "what's the deal here?"
>>
>> The guy pushing it is extremely smart and capable, so whatever it is
>> it's probably good.
> 
> I expect you'll find it is the codification of many of the development
> mentality and practices that you have been using for a long time.
> 
> Be cautious about how TDD applies to bottom-up design (i.e. finding
> things that work and clagging them together) v.s. top-down design. TDD
> works naturally with top-down design where all the yet-to-be-implemented
> are well understood and feasible.
> 
> Anybody that /thinks/ will realise that sometimes it is beneficial to do
> a "spike investigation" to quickly validate key concepts from
> top-to-bottom, and then to use that experience to do it "properly"
> using full-blown TDD.

It's not magic.  I've been geeking out on the COSMAC 1802 lately, because 
it was the first microprocessor I ever owned (I had an ELF-II kit).  The 
user's manual has an entire chapter extolling the virtue of SUBROUTINES 
(ooh, ahh) and how to implement them.  It's quite gushy about how using 
subroutines make your code better.  And yet, I've worked on lots of 
crappy code that has subroutines.

-- 

Tim Wescott
Wescott Design Services
http://www.wescottdesign.com

On 17/05/17 16:25, Tim Wescott wrote:
> On Wed, 17 May 2017 10:32:59 +0100, Tom Gardner wrote:
>
>> On 17/05/17 09:57, Reinhardt Behm wrote:
>>> AT Wednesday 17 May 2017 16:42, Tom Gardner wrote:
>>>
>>>> On 17/05/17 01:56, Don Y wrote:
>>>>> On 5/16/2017 3:51 PM, Tom Gardner wrote:
>>>>>> The other dysfunctional aspect of unit tests is that,
>>>>>> while they are very useful when making incremental improvements
>>>>>> during design, they can be a real impediment in a few months/years
>>>>>> time. The problem is that over time people forget which tests
>>>>>> demonstrate required properties, and which are merely ensuring
>>>>>> behaviour of implementation artifacts. At that point people are
>>>>>> afraid to make changes that break tests, even if the tests are
>>>>>> unimportant. At that point the codebase has become ossified.
>>>>>
>>>>> But that's true any time you (attempt to) nail down an aspect of a
>>>>> design.  Moreso if you don't provide a rationale for WHY the
>>>>> requirement (whether it be from a spec or a test) was imposed.
>>>>
>>>> Of course. Nonetheless, it happens - and zealots sometimes refuse to
>>>> admit it.
>>>
>>> Therefor any good development process demands that requirements
>>> (high-level,
>>> or low-level) must be traceable to system requirements or must be
>>> marked as design decisions. Then you have the WHY.
>>> A test can not be the source of a requirement. A test should also be
>>> traceable to sys-reqs.
>>> And hopefully the sys-reqs are good.
>>
>> We are in violent agreement.
>>
>> But my point is about the XP/Agile/TDD/Unit Test zealots that overstate
>> the benefits of those techniques and ignore their dysfunctional aspects.
>
> That's kind of the definition of a zealot.
>
> Something that Reinhardt -- and I think maybe you -- are missing, is that
> part of the reason for agile is that requirements don't remain static.
> As soon as people see a something working, the requirements change -- and
> saying "no, I'm sorry person-who-signs-checks, we're going to spend the
> next year making what you asked for initially and THEN we're going to
> entertain change requests".
>
> So you can't treat requirements as static things graved in stone.  Agile
> tries to deal with that, and as near as I can tell, only having nibbled
> at the edges of it, it does a reasonably good job of it for things that
> aren't terribly safety critical.  Agile is also new, so it's naturally
> going to attract zealots -- the trick is to see the value underneath the
> hype, and then make rational choices about what to do.

I understand and agree with all of that.

I once pushed for agile practices to be introduced into a
company for those reasons. I then saw the newly-trained
staff think it was a good idea to delete /all/ comments on
the religious principle that comments are bad because they
get out of sync with the code. They also changed private
functions and data to public so that they could be seen
by their unit tests - thereby encouraging future developers
to /misuse/ the classes in ways that are easily avoidable.

That doesn't mean agile is bad (it isn't!), only that
/unthinkingly/ following a process is bad.

On 17-05-17 19:47 , Don Y wrote:
> On 5/17/2017 8:07 AM, Niklas Holsti wrote:
>> On 17-05-17 13:54 , Don Y wrote:
>>> On 5/17/2017 3:12 AM, Reinhardt Behm wrote:
>>>>  [snips]
>>>> But I must confess I sometimes do something like this: When the
>>>> customer
>>>> does not really know what he wants or I myself need to get a feeling
>>>> how a useful user interface should be. Then I do prototyping this way.
>>>> Later the sys-reqs are derived from these prototypes and the software
>>>> is developed again according to these reqs. The prototyping-code goes
>>>> into a CVS-branch called "playground".
>>>
>>> I write user manuals, now, instead of specifications.  They have to
>>> address
>>> all of the same information that is presented in a specification --
>>> cuz the
>>> user needs to know why/when this "error" will be thrown, or that
>>> constraint
>>> imposed, etc.
>>
>> For my last product, I wrote a combined user manual and requirement
>> specification, using LibreOffice conditional text: set a document
>> variable one
>> way, it is a user manual; set the variable differently, and every
>> meaningful
>> paragraph gets a requirement number that can be referenced in tests and
>> validation matrices.
>>
>> Only drawback is that the paragraphs are rather shorter than in usual
>> prose.
>
> The problem, here, is that you have the same "data" represented in two
> different forms (views/documents).  So, there is the implicit concern
> that the two may be -- or become -- out of sync.  Like comments in code
> not agreeing with what the code is NOW doing (after some revision).

The _text_ of the document is unchanged in the two views, except for 
some meta-text paragraphs that explain the purpose and structure of the 
document. The "requirement specification" view only adds the formal 
machinery (requirement identifiers and requirement index) for 
tracebility with tests. The user manual and the specifications cannot go 
"out of sync".

-- 
Niklas Holsti
Tidorum Ltd
niklas holsti tidorum fi
       .      @       .