Documentation needs work

[alienbogart]

Hi everyone,

I know this is a FOSS project and I'm in no position to make demands, so please understand that it is not my intention to be antagonistic, but I need to make some criticism and I believe that being objective is in the best interest of the project.

Although I know some Python and a bit of Emacs Lisp, I am by no means a programmer, just a dedicated computer nerd. I am a Linux user, a shell user, a somewhat advanced Vim/Emacs (my init.rel currently has 1400 lines, down from 4000 lines). I have also used Tmux for a time as well.

I say this to convey that I am no stranger to large and complex programs, and I am very familiar with the documentation.

Nevertheless, I couldn't figure out how to configure and customize TinTin++ for my needs.

I wanted to use Tintin++ because it felt like a very customizable program that reminded me of the freedom I have on Emacs. However, the documentation seems to be targeted at those that already know how to use the program, which kinda defeats the purpose. I gotta be very honest here: I don't think I ever saw documentation as cryptic and lacking as TinTin's. The program seems great, but it's a black box and I ultimately gave up.

I know there is additional documentation, but I'm not finding the link at this moment. In any case, I can tell that the additional documentation is short and insufficient as well.

Someone recommended asking on Discord, but doing so would become annoying for everyone since I would be asking dozens of questions every day, basically forcing people to write the documentation for me message by message.

So I would like to make an earnest question here: is this project solely for the use of computer programmers? If the answer is "yes", then no change must be made. However, if the answer is "no", I strongly advise a concerted effort toward creating user-friendly documentation.

By "user-friendly documentation" I mean something more than a list of commands, classes, etc. There must be some indication of how to put the pieces together and accomplish whatever Tintin is able to accomplish.

Thanks.

[scandum]

If you type #help index tintin will explain the basics. The same text is available at this url: https://tintin.mudhalla.net/manual/index.php

Do you feel something is missing there? I guess we're having the same discussion on reddit, but it's probably easier to have it here. I'll see if I can put together a tutorial section, right now the manual and tutorial are kind of blended together, which isn't helpful. If you use #help without an argument it will show the tutorial entries in a different color.

[alienbogart]

Thanks for the link. That is certainly helpful for basic usage. But, if I was to use the program, I would need a lot more than that. Chiefly, there should be entire sections showing how all the elements of Tintin can actually go together to achieve some commonly needed functionalities, including the most advanced features.

As it is, Tintin's manual is little more than a command reference.

Mudlet's documentation is a good example of comprehensive documentation in the MUD client space. There's something for users of every level, allowing someone to progress from start to finish, increasing their understanding, and gradually mastering the program.

Another example, which I believe is relevant due to the apparent breadth and complexity of Tintin, would be the Emacs manual.

Also, while it is nice to have built-in help, all documentation should be available outside of the program as well.

[scandum]

I went ahead and published the more tutorial-ish sections of the manual as a stand alone html file. I updated the intro so it's a bit more clear how to get started with a simple command file. I still have to go over the rest.

https://scandum.github.io/tintin/tutorial.html

Showing how to build a modular script step by step is a good idea.

One of my main worries is sinking a lot of time into something that ends up being tl;dr for 90% of users.

[alienbogart]

https://scandum.github.io/tintin/tutorial.html

That is certainly a step in the right direction, thank you for doing that. I'll give Tintin another shot based on that tutorial.

One of my main worries is sinking a lot of time into something that ends up being tl;dr for 90% of users.

That is a risk, and I cannot anticipate the wants of all users by myself. However, it is my personal opinion that extensive work in friendly, extensive documentation can do for Tintin what it did for other projects complex projects such as Python, Vim, Emacs, and Tmux.

These are projects that communicate well both with developers and dedicated laymen such as myself, and I don't see why Tintin can't do the same.

You should also consider secondary effects. If Tintin had good documentation, I would probably be using it. And you better believe I would be spreading my knowledge online, making your job easier. Many would follow suit.

[LittleStar-VIP]

Regarding the manual, could I suggest adding an example of how to do regex match using #if
I wanna know how to do something like #if {"%1" == {[0-9]+[neswud]}}
so that I could match 1d, 2w, 3ne, etc.
This is just an example

[scandum]

You would need to use a second set of quotes around the argument on the right:

#if {"%1" == "{[0-9]+[neswud]}"}

Part of the syntax for #if is described in #math.

I'll see if I can come up with a good regex example for #help if.

[LittleStar-VIP]

Oh thank you I understood.

[LittleStar-VIP]

Also would you please add a description in the varriable or if section to instruct us how to check if a variable exist?
For example, if
one action trigger #unvariable {Test}
then I wanna do something if Test variable is existed and else do the other thing

[scandum]

Variable existence is covered in #help lists. To see if Test exists you would use

#if {&{Test} == 0} {#showme Variable named Test does not exist.}

[LittleStar-VIP]

Variable existence is covered in #help lists. To see if Test exists you would use

#if {&{Test} == 0} {#showme Variable named Test does not exist.}

Oh I just saw a old discussion mentioning that we could use
#if {&{Test}} {#show var test existed.};#else {#show var test not exist}

[LittleStar-VIP]

You would need to use a second set of quotes around the argument on the right:

#if {"%1" == "{[0-9]+[neswud]}"}

Part of the syntax for #if is described in #math.

I'll see if I can come up with a good regex example for #help if.

I try to follow your instruction, but the following command return no match, do you know what I am wrong? thank you.
#variable {test} {Hello};
#if {"$test" == "{H%*}"} {-sh oh match};
#else {-sh no match}

[scandum]

#help pcre has some information on perl compatible regular expressions. In your example you should use instead:

#if {"$test" == "H%*"} {#show oh match};

There's an active Discord channel where you might get answers to simple questions in a more timely manner.

https://discord.gg/gv7a37n

[LittleStar-VIP]

#help pcre has some information on perl compatible regular expressions. In your example you should use instead:

#if {"$test" == "H%*"} {#show oh match};

Thank you very much again.

There's an active Discord channel where you might get answers to simple questions in a more timely manner.

https://discord.gg/gv7a37n

Ok noted, will look at it.