michaeldesu
commented
1 month ago 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).
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.