Intro to using services via `craft.app` in templates about docs

[brandonkelly]

Just added a quick note about it on the Global Variables page.

As far as craft.app examples go, the plan is that we will start adding Twig examples to the service methods, and style the class reference more like API documentation (like https://docs.api.craftcms.com/), where code examples are displayed off to the right, and you can choose whether you want to view code examples in PHP or Twig.

[narration-sd]

that sounds a really good idea, especially as it will mean more useful documentation, as notes from both coding methods will be merged...also less work...

[carlcs]

Copy from a discussion on Slack:

Craft 2 only made a few of its service functions available in Twig, and all of them were nicely documented in the templating part of the docs where most of them came with nice examples to get you started quickly.

In 3 you now have access to all of Craft’s service functions via craft.app, and all of them are documented in the Class Reference already. I understand that it’s not really practical to have all functions documented in a second place, and it probably wouldn’t even help much because what I think is the most significant difference to Craft 2 docs of craft.request etc is compactness. Only the most usefull templating functions were documented, because more weren’t even available for use. This gave a nice overview of what you can do in Twig which is now lost and a real issue especially for beginners.

[brandonkelly]

Fair point.

[paul-frost]

I've just been pointed to this after getting help on Slack with segments.
I'd just like to re-iterate how the lack of real world examples in the documentation is making Craft 3 a really negative experience. I'm not a beginner but I'm also not a programmer. I keep hitting issues that I can't work out myself. I hate having to ask on SE or Slack how to do what seem such simple things. I search through SE threads trying all combinations of search questions and then usually find they refer to Craft 2.

[brandonkelly]

@paul-frost Thanks, we’re working on it.