[Cuis-dev] On the importance of documentation

[Juan Vuletich]

I fully agree with this.

Documenting Smalltalk is not the same as documenting a black box 
library. People should be encouraged to explore the system by 
themselves. Separate documentation should focus especially on the 
concepts and ideas that can not be easily discovered in that way.

Thanks,

On 5/12/2025 4:10 AM, Luciano Notarfrancesco via Cuis-dev wrote:
> Hi Hilaire,
> Thanks for the interesting reflections, and for the documentation efforts.
> I think perhaps the first thing newbies should learn is to explore the 
> system, to find out the details of how it works, 
> browser/senders/implementors/messages. Personally, every time I want 
> to do something in Cuis and I don’t know how, I just use these tools, 
> explore, search messages (guessing parts of selectors), find examples 
> of use in the image, perhaps change something and see how the system 
> reacts, etc. More specific documentation is great, of course, but as a 
> first step I would point any newbie trying to do anything with Cuis to 
> first learn the tools to explore the system. What do you think?
>
>
> On Thu, May 8, 2025 at 15:59 Hilaire Fernandes via Cuis-dev 
> <cuis-dev at lists.cuis.st <mailto:cuis-dev at lists.cuis.st>> wrote:
>
>     Some interesting reflections on documentation in the NumPy community:
>
>     https://labs.quansight.org/blog/2020/03/documentation-as-a-way-to-build-community
>
>     The text is a bit long, so I pasted below some interesting extracts.
>
>     *Why documentation is important.
>     *
>
>         [...] Having official high-level documentation written using
>         up-to-date content and techniques will certainly mean more
>         users (and developers/contributors) are involved in the NumPy
>         community.
>
>         So, if everybody agrees on its importance, why is it so hard
>         to write good documentation?
>
>
>     *What the corporate world does.
>     *
>
>         If we look at proprietary or com pany-backed software
>         projects, often professional technical writers are working on
>         the docs. Having access to these professionals to do the
>         documentation can make a huge difference. [...]
>
>
>     *What is the tendency in free software communities.
>     *
>
>         [..] As I got more involved in the open source world, I
>         realized that the people writing docs were not only invisible
>         but were sometimes actively discouraged. There is even a
>         differentiation in naming such contributions; have you ever
>         heard of a "core docs developer"? [..] _Even when the
>         community is welcoming, documentation is often seen as a "good
>         first issue", meaning that the docs end up being written by
>         the least experienced contributors in the community. [..]
>         However, it may transfer the responsibility of one of the most
>         crucial aspects of any project to novice users, who have
>         neither the knowledge or the experience to make decisions
>         about it._
>
>     -- 
>     http://mamot.fr/@drgeo
>
>     -- 
>     Cuis-dev mailing list
>     Cuis-dev at lists.cuis.st <mailto:Cuis-dev at lists.cuis.st>
>     https://lists.cuis.st/mailman/listinfo/cuis-dev
>


-- 
Juan Vuletich
cuis.st
github.com/jvuletich
researchgate.net/profile/Juan-Vuletich
independent.academia.edu/JuanVuletich
patents.justia.com/inventor/juan-manuel-vuletich
linkedin.com/in/juan-vuletich-75611b3
twitter.com/JuanVuletich

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cuis.st/mailman/archives/cuis-dev/attachments/20250519/537a8d09/attachment.htm>