<div dir="ltr"><div dir="ltr"><div>Hi Hilaire,<br><br>Sometimes anger can drive positive actions and reactions, but in the long run, it is unhealthy, and unsafe fuel to burn.<br><br></div>Your mention of Adele Goldberg is spot on, and reminded me of a couple of things she said during her <a href="https://www.youtube.com/watch?v=fjDVaHNA8ls">Oral History interview</a>. The first is about documentation. She is speaking about a client they had in the CIA:<br><br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">…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…</blockquote><div><br></div><div>The second thing is that during her time presiding the ACM she had to learn how to channel volunteers towards fruitful outcomes:</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><b>Goldberg:</b> 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.</blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><b>Mashey:</b> Yeah, right, right, yeah. </blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><b>Goldberg:</b> 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.</blockquote><div><br></div><div>Maybe a way to encourage prospective contributors is to review <a href="https://cuis.st/community">https://cuis.st/community</a>; Should we include a link to <a href="https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev/wiki/Helping-Cuis">https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev/wiki/Helping-Cuis</a>?</div><div><br></div><div>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.<br><br>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.</div><div><br></div><div>-- <br></div><div>Eze </div></div><br><div class="gmail_quote gmail_quote_container"><div dir="ltr" class="gmail_attr">On Sun, 18 May 2025 at 09:29, Hilaire Fernandes via Cuis-dev <<a href="mailto:cuis-dev@lists.cuis.st">cuis-dev@lists.cuis.st</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><u></u>
<div bgcolor="#FFFFFF">
<p><font size="4"><rant on></font></p>
<p><font size="4">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 <b>undocumented</b>. It is
ok, we are Smalltalkers, " we have the best system of the world,
Hue, we can figure it out! Hue." </font></p>
<p><font size="4">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. </font></p>
<p><font size="4">(No documentation = No feature) => Next !<br>
</font></p>
<p><font size="4">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".</font></p>
<p><font size="4">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. </font></p>
<p><font size="4">-<b>u</b>d "$HOME/$USERDATA/Resources"<br>
</font></p>
<p><font size="4">Remember a few days ago, I posted about the
work-in-progress regarding the command line options
(<a href="https://github.com/DrCuis/Workbench/wiki/Command_Line_Options" target="_blank">https://github.com/DrCuis/Workbench/wiki/Command_Line_Options</a>),
I asked for contributions to complete the options I didn't know
about. I got zero, nada, que tchi, peau de balle, answer...<br>
</font></p>
<p><font size="4">So this morning, I write a bit more documentation.
Of course I could not care and egoistically not share my new
know how.<br>
</font></p>
<p><font size="4">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.<br>
</font></p>
<p><font size="4"></rant off></font></p>
<p><font size="4">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.</font></p>
<p><font size="4">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.<br>
</font></p>
<p><font size="4">So even tiny documentation can make a difference.</font></p>
<p><font size="4">Thanks<br>
</font></p>
<p><font size="4"><br>
</font></p>
<pre cols="72">--
<a href="http://mamot.fr/@drgeo" target="_blank">http://mamot.fr/@drgeo</a></pre>
</div>
-- <br>
Cuis-dev mailing list<br>
<a href="mailto:Cuis-dev@lists.cuis.st" target="_blank">Cuis-dev@lists.cuis.st</a><br>
<a href="https://lists.cuis.st/mailman/listinfo/cuis-dev" rel="noreferrer" target="_blank">https://lists.cuis.st/mailman/listinfo/cuis-dev</a><br>
</blockquote></div></div>