Re: [OT] I got a JOB!!!

From	Don Y <blockedofcourse@foo.invalid>
Newsgroups	comp.arch.embedded
Subject	Re: [OT] I got a JOB!!!
Date	2017-05-17 09:47 -0700
Organization	A noiseless patient Spider
Message-ID	<ofhuji$6mt$1@dont-email.me> (permalink)
References	(8 earlier) <ofh332$26n$2@dont-email.me> <dNUSA.16638$C56.1284@fx34.am4> <ofh7fs$g96$1@dont-email.me> <ofh9u9$ntk$1@dont-email.me> <eo3792Fd8c6U1@mid.individual.net>

Show all headers | View raw

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.

Thread

[OT] I got a JOB!!! Tim Wescott <seemywebsite@myfooter.really> - 2017-05-16 13:49 -0500
  Re: [OT] I got a JOB!!! Steve Wilson <no@spam.com> - 2017-05-16 19:04 +0000
  Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-16 12:14 -0700
    Re: [OT] I got a JOB!!! Tim Wescott <tim@seemywebsite.really> - 2017-05-16 14:41 -0500
      Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-16 14:01 -0700
        Re: [OT] I got a JOB!!! mike <ham789@netzero.net> - 2017-05-16 14:42 -0700
        Re: [OT] I got a JOB!!! Tim Wescott <seemywebsite@myfooter.really> - 2017-05-16 17:09 -0500
          Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-16 16:42 -0700
        Re: [OT] I got a JOB!!! Clifford Heath <clifford.heath@gmail.com> - 2017-05-17 09:00 +1000
  Re: [OT] I got a JOB!!! eric.jacobsen@ieee.org - 2017-05-16 20:17 +0000
    Re: [OT] I got a JOB!!! Tim Wescott <tim@seemywebsite.really> - 2017-05-16 15:24 -0500
      Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-16 22:05 +0100
        Re: [OT] I got a JOB!!! Tim Wescott <seemywebsite@myfooter.really> - 2017-05-16 17:11 -0500
          Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-16 23:51 +0100
            Re: [OT] I got a JOB!!! Tim Wescott <seemywebsite@myfooter.really> - 2017-05-16 18:32 -0500
              Re: [OT] I got a JOB!!! Clifford Heath <clifford.heath@gmail.com> - 2017-05-17 09:41 +1000
                Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 09:35 +0100
                Re: [OT] I got a JOB!!! Clifford Heath <no.spam@please.net> - 2017-05-17 19:03 +1000
                Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 10:31 +0100
                Re: [OT] I got a JOB!!! Clifford Heath <no.spam@please.net> - 2017-05-17 23:07 +1000
              Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 09:41 +0100
                Re: [OT] I got a JOB!!! Paul <paul@pcserviceselectronics.co.uk> - 2017-05-17 10:10 +0100
                Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 10:34 +0100
                Re: [OT] I got a JOB!!! Paul <paul@pcserviceselectronics.co.uk> - 2017-05-17 15:59 +0100
                Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 18:04 +0100
              Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 18:02 +0100
            Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-16 17:56 -0700
              Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 09:42 +0100
                Re: [OT] I got a JOB!!! Reinhardt Behm <rbehm@hushmail.com> - 2017-05-17 16:57 +0800
                Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 10:32 +0100
                Re: [OT] I got a JOB!!! Reinhardt Behm <rbehm@hushmail.com> - 2017-05-17 18:12 +0800
                Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-17 03:54 -0700
                Re: [OT] I got a JOB!!! Reinhardt Behm <rbehm@hushmail.com> - 2017-05-17 21:57 +0800
                Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-17 09:36 -0700
                Re: [OT] I got a JOB!!! Niklas Holsti <niklas.holsti@tidorum.invalid> - 2017-05-17 18:07 +0300
                Re: [OT] I got a JOB!!! Robert Wessel <robertwessel2@yahoo.com> - 2017-05-17 10:44 -0500
                Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-17 09:47 -0700
                Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-17 10:18 -0700
                Re: [OT] I got a JOB!!! Niklas Holsti <niklas.holsti@tidorum.invalid> - 2017-05-17 20:25 +0300
                Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-17 12:01 -0700
                Re: [OT] I got a JOB!!! Tim Wescott <tim@seemywebsite.really> - 2017-05-17 10:25 -0500
                Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 18:22 +0100
                Re: [OT] I got a JOB!!! Tim Wescott <seemywebsite@myfooter.really> - 2017-05-17 12:36 -0500
                Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 18:45 +0100
                Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-17 03:42 -0700
  Re: [OT] I got a JOB!!! "billbowden" <bperryb@bowdenshobbycircuits.info> - 2017-05-16 15:04 -0700
    Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-16 15:30 -0700
  Re: [OT] I got a JOB!!! Martin Riddle <martin_ridd@verizon.net> - 2017-05-16 20:02 -0400
  Re: [OT] I got a JOB!!! krw@notreal.com - 2017-05-16 20:40 -0400
  Re: [OT] I got a JOB!!! Randy Yates <randyy@garnerundergroundinc.com> - 2017-05-17 09:12 -0400
    Re: [OT] I got a JOB!!! Tim Wescott <tim@seemywebsite.really> - 2017-05-17 10:02 -0500
      Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 18:11 +0100
        Re: [OT] I got a JOB!!! Tim Wescott <seemywebsite@myfooter.really> - 2017-05-17 12:21 -0500
          Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 18:36 +0100
            Re: [OT] I got a JOB!!! Tim Wescott <seemywebsite@myfooter.really> - 2017-05-17 12:43 -0500
              Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 18:55 +0100
                Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 18:57 +0100
                Re: [OT] I got a JOB!!! Tim Wescott <seemywebsite@myfooter.really> - 2017-05-17 13:28 -0500
                Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-17 20:08 +0100
  Re: [OT] I got a JOB!!! boB K7IQ <boB@everett.wa> - 2017-05-17 21:30 -0700
    Re: [OT] I got a JOB!!! Tim Wescott <tim@seemywebsite.really> - 2017-05-18 00:03 -0500
    Re: [OT] I got a JOB!!! Tom Gardner <spamjunk@blueyonder.co.uk> - 2017-05-18 08:18 +0100
      Re: [OT] I got a JOB!!! boB K7IQ <boB@everett.wa> - 2017-05-18 22:56 -0700
        Re: [OT] I got a JOB!!! Vassilis Spiliopoulos <vassilis@vask1lux.de> - 2017-05-19 14:31 +0300
          Re: [OT] I got a JOB!!! Tim Wescott <tim@seemywebsite.really> - 2017-05-19 10:39 -0500
            Re: [OT] I got a JOB!!! Vassilis Spiliopoulos <vassilis@vask1lux.de> - 2017-05-19 23:02 +0300
              Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-19 13:12 -0700
                Re: [OT] I got a JOB!!! dplatt@coop.radagast.org (Dave Platt) - 2017-05-19 15:00 -0700
                Re: [OT] I got a JOB!!! Don Y <blockedofcourse@foo.invalid> - 2017-05-19 16:05 -0700
              Re: [OT] I got a JOB!!! boB K7IQ <boB@everett.wa> - 2017-05-21 01:46 -0700
                Re: [OT] I got a JOB!!! Vassilis Spiliopoulos <vassilis@vask1lux.de> - 2017-05-21 17:31 +0300
                Re: [OT] I got a JOB!!! John S <Sophi.2@invalid.org> - 2017-05-21 13:31 -0500
                Re: [OT] I got a JOB!!! krw@notreal.com - 2017-05-21 16:47 -0400

csiph-web