Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

documentation: improve the explanation about backtick templates #9281

Open
michaeldesu opened this issue Jul 31, 2024 · 1 comment
Open

documentation: improve the explanation about backtick templates #9281

michaeldesu opened this issue Jul 31, 2024 · 1 comment
Assignees
Labels
Area/BBE Issues related to BBEs. Kind/Language Type/Improvement Improvements required on the website.

Comments

@michaeldesu
Copy link

Description:
As a new learner of Ballerina, good documentation is really critical. I think the docs and examples are great, but there are some rough areas and minor typos (I'll probably report these also in another ticket).

The topic is about backtick templates.

Describe your problem(s)

Those are documented but I think it's not presented in an intelligible fashion, or the ordering is out of sequence.

Please see this discord thread for background.

Describe your solution(s)

A better introduction about those is needed (along the lines of this). Currently the first article in the section starts with "A raw template is a backtick template without a tag. Exposes result of phase 1 without further processing" but doesn't define what a 'tag' is, nor 'phase 1' - that terminology is a little strange and is not explained upfront (a diagram to point out where the tag is in the code might be helpful). The concept of phase 1 & 2 is introduced in the 2nd article. Those pages should get a revamp for clarity.

Suggested Labels (optional):

documentation

Thanks to Sasindu Alahakoon for his assistance.

@michaeldesu michaeldesu added the Type/Improvement Improvements required on the website. label Jul 31, 2024
@SasinduDilshara SasinduDilshara added the Area/BBE Issues related to BBEs. label Jul 31, 2024
@michaeldesu
Copy link
Author

Above I alluded to perhaps it's better to swap the order of the first 2 template pages in the doc. I've just been reading the docs on Table, and I think it's a similar story there. I think swapping the 1st and 2nd pages would present a better introduction to the reader (i.e. 'table types' comes first as an introduction & basic declaration, and then 'table' page talks about how to add/put etc).

@anupama-pathirage anupama-pathirage transferred this issue from ballerina-platform/ballerina-distribution Aug 30, 2024
@heshanpadmasiri heshanpadmasiri self-assigned this Sep 13, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Area/BBE Issues related to BBEs. Kind/Language Type/Improvement Improvements required on the website.
Projects
Status: Backlog
Development

No branches or pull requests

5 participants