Ftn I/Os documentation best practices

On 28 Jun 2022 at 20:33:42 CEST, "Don Y" <blockedofcourse@foo.invalid> wrote:

> On 6/28/2022 7:35 AM, Stephen Pelc wrote:
>> As others have said it needs discipline. Discipline comes from
>> management. As the boss, I have made it quite clear that use
>> of DocGen is a requirement to work at the company. In turn
>> it is my job to ensure that people know how to use the tool.
> 
> You can "legislate" the use of a tool or adherence to a standard.
> But, these are subjective issues -- not like "derate all caps by
> 40%" (which can be independently, mathematically verified).  You
> rely on individual "employees" for their judgement as to the
> effectiveness of their documentation.  Likewise, the efficacy
> of their test/validation efforts.

Followed by lots more pointless whining.

Changing company culture is really hard, even for my own
company. I'm an electronics engineer by training, and I have
been writing software since 1967, and I still write production
code.

I may not have fired people directly for not being good enough,
but I have certainly strongly encouraged them to get another job.

Stephen

-- 
Stephen Pelc, stephen@vfxforth.com
MicroProcessor Engineering, Ltd. - More Real, Less Time
133 Hill Lane, Southampton SO15 5AF, England
tel: +44 (0)23 8063 1441, +44 (0)78 0390 3612, +34 649 662 974
http://www.mpeforth.com - free VFX Forth downloads

On 6/29/2022 5:36 AM, Stephen Pelc wrote:
> On 28 Jun 2022 at 20:33:42 CEST, "Don Y" <blockedofcourse@foo.invalid> wrote:
> 
>> On 6/28/2022 7:35 AM, Stephen Pelc wrote:
>>> As others have said it needs discipline. Discipline comes from
>>> management. As the boss, I have made it quite clear that use
>>> of DocGen is a requirement to work at the company. In turn
>>> it is my job to ensure that people know how to use the tool.
>>
>> You can "legislate" the use of a tool or adherence to a standard.
>> But, these are subjective issues -- not like "derate all caps by
>> 40%" (which can be independently, mathematically verified).  You
>> rely on individual "employees" for their judgement as to the
>> effectiveness of their documentation.  Likewise, the efficacy
>> of their test/validation efforts.
> 
> Followed by lots more pointless whining.

First-hand examples of how "discipline" doesn't work, in practice.

If you've been "lucky", then "good for you".  You're likely the
Exception and not the Rule.  You've led a blessed existence.  So,
likely aren't competent to comment on life with "less angelic"
employees.

Please let us know your progress on addressing world hunger...

> Changing company culture is really hard, even for my own
> company. I'm an electronics engineer by training, and I have
> been writing software since 1967, and I still write production
> code.

Now, imagine your products hosted code written by other people.
Outside of your organization.  What sort of reach do you have
into THEIR corporate culture?  Do you act as PHYSICAL gatekeeper
and prohibit "unblessed" code from being installed on your
products?  Do *you* take on the job of creating every application
and hardware module that any of your users might conceivably want
(because you trust your own efforts, exclusively)?

How eager will you be for your customers to have their experiences
with YOUR product tainted by those other "components"?  Will they
be sophisticated enough to know that the quality issues arise not
from YOUR portion of the work but from the efforts of others?
Will they be able to determine *which* others (so they can excise them)?

[Imagine the resolver in your PC being unreliably written by X.
Will the user recognize that the resolver's faults are the
reason behind the poor performance of the browser?  Or, flaws
in the filesystem implementation the reason for application
failures/data loss?  Or...]

I want mechanisms that make it easy for people to "do the right
thing", despite their inclination to do otherwise.  I'm not
keen on waiting for them to "see the light".  Nor do I have
the ability to coerce them to do so.

But, if I make The Right Path easier to follow than the "wrong"
ones, they are more likely to follow it out of laziness/self-interest.

> I may not have fired people directly for not being good enough,

Why not?  Especially if it's YOUR company?  Imagine the hesitance
to doing so when The Boss is just an employee of some corporate
entity -- not *his* name above the door.

> but I have certainly strongly encouraged them to get another job.

So, you "reworked" any work they did for you up until the time
of their departure?  Or, did you just let it slide -- *into* your
products?