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

[Ezequiel Birman]

Hi Hilaire,

Sometimes anger can drive positive actions and reactions, but in the long
run, it is unhealthy, and unsafe fuel to burn.

Your mention of Adele Goldberg is spot on, and reminded me of a couple of
things she said during her Oral History interview
<https://www.youtube.com/watch?v=fjDVaHNA8ls>. The first is about
documentation. She is speaking about a client they had in the CIA:

…He showed me this prototype that they had been working on and the first
> thing that floored me was I thought they were supposed to tell us when they
> took our research and started doing something with it. But the real thing
> that floored me was there were no books. There was no documentation. There
> were talks and in those talks we would say, “If you want to know how to do
> something, you just look and read the code and it pretty much self
> documents.” I mean we were so full of ourselves…


The second thing is that during her time presiding the ACM she had to learn
how to channel volunteers towards fruitful outcomes:


> *Goldberg:* So I got some [executive management experience.] I learned
> what happens when you have a lot of people working for you who you can’t
> fire because they’re volunteers.

*Mashey:* Yeah, right, right, yeah.

*Goldberg:* What you really have to do is figure out how to engage them in
> good projects, how to get rid of projects that really were not going
> anywhere, and how to leverage the positive. So I was getting some very good
> organizational learning.


Maybe a way to encourage prospective contributors is to review
https://cuis.st/community; Should we include a link to
https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev/wiki/Helping-Cuis?

As an occasional, amateur user, My M.O is to leave the crime scene in a
better state when compared with how I found it first, for some definition
of better. If you feel that efforts should be focused on a certain area,
like documentation, then I welcome your guidance and leadership. I'll give
the new wiki a cursory review in the following days.

Maybe a combination of linting tools, meta-data annotation and
conversational “AI” can help here. As you found out, the command line
options you needed, are printed and explained when you pass -h. So
documentation could be scored with regards to a criteria, and in that
particular case, qualified as insufficient, and maybe queried by asking a
question to an “agentic” LLM.

-- 
Eze

On Sun, 18 May 2025 at 09:29, Hilaire Fernandes via Cuis-dev <
cuis-dev at lists.cuis.st> wrote:

> <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
>
> --
> Cuis-dev mailing list
> Cuis-dev at lists.cuis.st
> https://lists.cuis.st/mailman/listinfo/cuis-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cuis.st/mailman/archives/cuis-dev/attachments/20250519/12236130/attachment-0001.htm>