Getting help with Cuis

How to get answers, and how to report bugs so they get fixed.

The value of documentation

In the Cuis community, questions are most welcome. The main place for them is our mail list. In this space we value free speech, and at the same time we want an open and warm place where everybody can feel comfortable.

Still, besides the documentation on this site and at DrCuis, there are very good books, web pages, blogs and online videos that include descriptions of the ideas and intentions behind the code in the Cuis system. These are generally better than answers in the mail list, because they were written with great care. Questions on the mail list are often better for filling in details, for example, Cuis-specific details when you’re reading a non-Cuis-specific book.

For any Open Source project, questions are especially valuable if they point to some aspect not covered in enough clarity and detail in the documentation. Good questions help us refine documentation, or fix annoyances in the system. You know, we old-timers don’t read the documentation we wrote very often, and we tend to get used to small annoyances in the system to the point where we don’t see them any more. Good questions, complaints and bug reports are extremely helpful!

Still, questions that can be addressed by reading the documentation or a quick query to the system can sometimes feel annoying to maintainers. Authors can carefully write some explanation, investing several hours, and making that part of the documentation. Or we can instead write 10 times about the same issue, only when someone asks, each time improvising a low-quality ten-minute email. The first option results in higher quality material that can benefit many people over the course of years. The second option gives a low-quality answer to just one person, which may never be read again.

So, if you read the documentation first, and then point to flaws or missing parts, you are really helping us make a better system. This can’t be stressed enough. We really, really, really, very much, prefer this!

The value of an open system

Also keep in mind that most languages and frameworks are what is called “black box”. You only get the APIs or language constructs to use. If documentation is unclear or missing, your only resource is to ask someone for help. But, as Dan Ingalls says in his “Design Principles Behind Smalltalk”, Smalltalk tries to offer a completely different experience. In Smalltalk, all the libraries are “white box”. You are encouraged to look in detail at what they are doing. Time spent learning how to inspect and query the system is the best investment you can make in Smalltalk. Then, your questions will be better, and the answers will be better too. Your feedback after reading the documentation and the code will result in real improvement in both.

Reporting bugs

Sometimes you may find yourself in a situation where it seems something is not working well in the base system or some package (not in your own code). Your reaction may be “this must be a bug”. OK. How do we get that bug fixed?

Incidents

What you saw is not actually the bug. What you experienced is an incident. You expected some behavior and got a different, wrong behavior. This is called an Incident. The bug is the cause behind it. Why is this distinction important? Because what we can see are incidents, but what we need to fix is bugs! We need to find a way to cross that gap. System maintainers can’t work with incidents. We need something better. We need Bug Reports.

Bug reports

When you face an incident, we need you to produce a bug report. Writing Bug Reports is not trivial! There’s no need to repeat here what has been already written. Please read How to write an Effective Bug Report. Writing such bug reports and posting them to our mail list or the appropriate GitHub repo (with a mail to the list too, please) is the way to get a good number of eyes on them, and maximize the chance of a quick fix!

Happy exploring!