documentation

Anything beyond the basics in using the LiveCode language. Share your handlers, functions and magic here.

Moderators: Klaus, FourthWorld, heatherlaine, kevinmiller, robinmiller

Post Reply
mwieder
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 2993
Joined: Mon Jan 22, 2007 7:36 am
Location: Berkeley, CA, US
Contact:

documentation

Post by mwieder » Tue Mar 10, 2020 4:31 am

One of my favorite talks from this year's SCaLE (the stream is over seven hours, but the talk is just the first hour and starts about five minutes in):
https://youtu.be/sleN6J6R3ag?t=292

How to create documentation for an open-source project, what people expect from that documentation, how to organize it, etc.

tperry2x
Posts: 22
Joined: Wed Apr 22, 2020 9:58 pm

Re: documentation

Post by tperry2x » Thu Apr 23, 2020 7:48 pm

That's a wealth of information as far as documentation goes.
Having said that, if a program is designed in an intuitive way, then less documentation is required.

bogs
Posts: 4627
Joined: Sat Feb 25, 2017 10:45 pm

Re: documentation

Post by bogs » Thu Apr 23, 2020 8:05 pm

tperry2x wrote:
Thu Apr 23, 2020 7:48 pm
if a program is designed in an intuitive way, then less documentation is required.
I wouldn't make any large wagers on that one. One person's 'intuitive' is another person's quagmire.
aPic_programmerUiDesign.png
Documenation? Who needs it....!
aPic_programmerUiDesign.png (7.02 KiB) Viewed 1068 times
Image

tperry2x
Posts: 22
Joined: Wed Apr 22, 2020 9:58 pm

Re: documentation

Post by tperry2x » Thu Apr 23, 2020 8:25 pm

True, but that's perhaps just bad design. You can have a complicated program - but as long as you explain underneath what the options do, have the documentation next to the button.
Image

bogs
Posts: 4627
Joined: Sat Feb 25, 2017 10:45 pm

Re: documentation

Post by bogs » Thu Apr 23, 2020 8:39 pm

Again, I think you are giving way too much credit to people that likely don't think like you, me, or humans, and despite being out in the world, have an understanding and comprehension level of a 2 day old. Ok, ok, *if* they are able to actually read, maybe a 3 day old.

The stories I could tell you... :cry:

Anyway, like all else in the world, 'intuitive' isn't the same for everyone. You might intuitively look both ways before crossing the street, but your neighbor Sam there, finds it intuitive to do a silly walk and hope he makes it.
Image

SparkOut
Posts: 2169
Joined: Sun Sep 23, 2007 4:58 pm

Re: documentation

Post by SparkOut » Thu Apr 23, 2020 10:25 pm

Ok, here's a flippant comment: could you redesign the wGetGUI in the style of the Tweaker GUI so that I could intuitively know what I need to choose, to make it do what I need to do and understand what it is that I am doing, and what it is that I want to do?

A clear interface is always a good thing. But the interface is not always sufficient to explain and teach. Helping the user understand his or her own needs in the context of the software's purpose is often a challenge, and often is overlooked because "anyone using the software for its purpose must know what the purpose is, so they must know what the options are, and how to set them".

Post Reply

Return to “Talking LiveCode”