[Cuis-dev] On the importance of Documentation ! Even tiny one.

[Hilaire Fernandes]

<rant on>

I posted yesterday, late at night, about my struggle to turn a Cuis 
application as a multi-user application installed in multi-user system 
as GNU/Linux. I had to deal with the Cuis start-up sequence and as well 
its command line option it accepts. All these features are 
*undocumented*. It is ok, we are Smalltalkers, " we have the best system 
of the world, Hue, we can figure it out! Hue."

My clock tracker indicates I spent about 7-8h on that topic, most of 
this time to dig to understand what the system does and adapt the code. 
It's ok, I can offer to waste a bit of my time. However, most people 
will not, particularly people new to Cuis or Smalltalk, they will dig a 
bit, very likely unwisely because of the lack of know how, then they 
will hit the wall of undocumented crucial features. Those people will 
conclude, rightly, that the system is not mature, which is perfectly 
valid from their perspective.

(No documentation = No feature) => Next !

You can't expect people will always dig on to understand the feature. 
"Hue, But our system is open to all eyes, people can learn from it." 
This stance is perfectly valid in a world of unlimited time, but very 
stupid in a constrained world, the real world. It is great to be able to 
dig in the system, and to learn to do it. But it is not precisely what a 
newbie could do or could do rightly. There the "No documentation = No 
feature".

Back to my problem, this morning I just have to add one letter in my 
start-up script (mostly), to get it work. YES ONE LETTER, and it gets 
solved. ONE LETTER of an undocumented feature.

-*u*d "$HOME/$USERDATA/Resources"

Remember a few days ago, I posted about the work-in-progress regarding 
the command line options 
(https://github.com/DrCuis/Workbench/wiki/Command_Line_Options), I asked 
for contributions to complete the options I didn't know about. I got 
zero, nada, que tchi, peau de balle, answer...

So this morning, I write a bit more documentation. Of course I could not 
care and egoistically not share my new know how.

Writing documentation is a Sisyphus task. This remind me about people 
collecting the classic Smalltalk books (blue, green, pink, choose your 
color). This is so unfair for Mrs Goldberg. Those authors likely spent 
vast among of time writing these documentations, and it brings a lot of 
awareness about Smalltalk, a huge, if not a major contributions. But 
when you think Smalltalk, you don't immediately think about Mrs 
Goldberg, I fell it is so unfair. Was it a task only women can conduct; 
not a task for men, doing hype conferences no one understand about, nor 
really care about too to be honest.

</rant off>

Hannes and I spend several hours thinking how to design a documentation 
system for the benefit of Cuis. It is in place, it is easy to navigate 
in, it is easy to contribute, it is easy to write down incomplete notes. 
There is no excuse.

Writing documentation should be understood like your dental hygiene. You 
can decide to spend daily 3x5 min of your free time to take care of 
yourself and avoid serious health issues months, years or even decades 
later. When you learn something new with Cuis, ask yourself "Will it be 
useful to other?" "Yes, I can take 5 min of my time to write a few 
notes, even incomplete in the DrCuis workbench" and very likely it will 
be useful to yourself months or even years later when looking back for 
documentation on a given feature or know-how.

So even tiny documentation can make a difference.

Thanks


-- 
http://mamot.fr/@drgeo
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cuis.st/mailman/archives/cuis-dev/attachments/20250518/c7126768/attachment.htm>