Improve TVM Instructions Table Readability

[reveloper]

Summary

Modification of the standard table format on the page https://docs.ton.org/learn/tvm-instructions/instructions to a wider display format.

Bounty Context

Why it's Important?
The TVM Instructions table is an essential resource for developers on the TON Blockchain. Improving its readability will enhance developer experience and efficiency.

Problem showcase
The current table formatting makes it difficult to read the TVM codes and their corresponding descriptions. A wider format is needed for easier reading and a better understanding of the given information.

Potential Solution
One should research solutions for the table layout to a wider format, the readability of the table should be significantly improved. Clear demarcation between each TVM Instruction and its corresponding information will lead to easier comprehension by developers. This layout redesign should implement user-friendly elements without loss of any content.

Clarified Details

1. Make a page without sidebars.
   Update TVM Instruction pages according to the format of this page(src/pages/hacktonberfest.tsx)
2. Make an optimal table structure. Make the table as convenient as possible for readability in the table itself, taking into account priority:
   Fift Syntax, Stack, Description - Always
   Gas - Sometimes
   Opcode - almost never.
3. Support the main search bar.
   Early we split the original one-page list, to make possible searches (and it works at the moment). This is very important to keep the opportunity to find OP codes by fift syntax descr from the main search bar and redirect developers to convenient for reading page.

References

• https://docs.ton.org/learn/tvm-instructions/instructions

REWARD

• SBT Bounty Reward
• 300 USD in TON

✨ Created with the help of TON Bounties Creator Bot.

[mbaneshi]

In case of approved ,I am ready to undertake task.

[mbaneshi]

These days horizontal scrolling is the main problem.
my suggestion is to put some content away from the table. I myself for readability adjust it.

This gist about the 1270 line, just summarizes TVM instruction.Maybe useful for resoving this issue.

[mbaneshi]

This repo, also summarizes the Fift pdf whitepaper, This may be also useful.

[liketurbo]

As "Stack" and "Gas" are not unique (meaning you are not searching by these fields) and nullable for "Stack," there might be an argument to move them into "Description" with an icon indications. Also making headers sticky would've helped in the navigation of a large document (just a nit).

Anyway, if you like the proposed solution feel free to assign me for a small $100 fee 😊

[reveloper]

@liketurbo, could you show an example(screenshot) of what this could look like? I'd ask you to try with the most "heavy" description, to stress test this hypothesis.

I agree, that the "GAS" field is not a key for searching, on the other hand we should think about convenient readability for this field.

[liketurbo]

@reveloper Yes, sure.

Provided screenshots are before and after respectively on my 1920 screen.

Here's changes' descriptions:

• Gas moved in the description field after a newline
• Stack goes after Gas as it's nullable thus avoiding position oscillation
• Description shortened by 3x (header x's) as even after removing 2 columns there's still small horizontal scroll

Acknowledged drawbacks:

• Reduced rows per page 10 before and 7 after
• Shrined description field by 3x (header x's)

[mbaneshi]

In the past, when we wanted to see the most right column we should scroll down, put scroll bar to the right, and then come back to see it. It is now much better.

[reveloper]

@liketurbo, thank you for such deep work, I appreciate that you spent time researching this issue.

At first sight, I thought this was a great solution.
But, as our goal is to create convenient docs for developers, I tried to collect feedback about this solution from the Developer Community who have experience working with TVM Instructions, and I faced the fact, that this kind of solution doesn't help at all.

I quote some text which I believe could be helpful for work:

1. The field with the stack name is critical. Personally, for me the following list of fields is used:
Fift Syntax, Stack, Description - Always
Gas - Sometimes
Opcode - almost never.

2. The information about the stack column removed (hidden) for some reason, even though it's one of the key pieces of information.
As references, I suggest the following pages:
I like the visuals and explanations for each opcode at https://www.evm.codes/.
I also appreciate the introductory information on how to read opcodes at https://ethervm.io/.

3. In any case, you should provide the option to hide the left and right navbars.

Please, make sure you are working with the new version of TVM Instructions pages.

[liketurbo]

@reveloper

What do you think about using accordions similar to evm.codes and moving the stack field into them? If it is essential to keep the stack field in the current format, how about hosting the full version of "TVM Instructions" on a separate website, again akin to the references you provided, and embedding a tablet version within the docs page?

I'm also providing a suggested version with removed left and right navbars as it's easy to prototype and it's a viable solution (screens below).

[reveloper]

@liketurbo,

I believe we should not use a separate website since we already have a CSV list on GitHub. Regarding the hidden bars, do you know if they can be implemented in a dynamic/static mode for TVM Instruction pages?

[reveloper]

I clarified the expected result for this bounty:

1. Make a page without sidebars.
   Update TVM Instruction pages according to the format of this page(src/pages/hacktonberfest.tsx)
2. Make an optimal table structure. Make the table as convenient as possible for readability in the table itself, taking into account priority:
   Fift Syntax, Stack, Description - Always
   Gas - Sometimes
   Opcode - almost never.
3. Support the main search bar.
   Early we split the original one-page list, to make possible searches (and it works at the moment). This is very important to keep the opportunity to find OP codes by fift syntax descr from the main search bar and redirect developers to convenient for reading page.

@liketurbo, would you like to finish this task?

[liketurbo]

@liketurbo, would you like to finish this task?

Certainly! I would be happy to complete this task.

Question: Should separate pages also be updated in the new format?

[reveloper]

@liketurbo, great!

Should separate pages also be updated in the new format?

Yes, but only if the search will work with this update. It's necessary to check. Otherwise, do this only for the one-page archive version.

The best version is - the one-page TVM Instruction without sidebars which supported by algolia search.