Expanding on Gantry's Documentation
-
-
- Ryan M Pierson
- Sr. Rocketeer
- Posts: 243
- Thanks: 164
- Technical Writer
-
Brian Shea wrote:
My point is that the docs still read from a 'developers' view, and doesn't seem to address the simple non-tech person.
Hello there,
This is one of the reasons I wrote the majority of the documentation we have at RocketTheme. Unlike most of our team, I'm not a developer, at all. I could probably piece together HTML and a YAML file, but beyond that I depend on our dev team to put together many of the examples you see in the advanced section of our documentation.
Having written the documentation from my own perspective, as someone that probably couldn't piece together more than a few lines of Twig, it is already pretty stripped-down basic.
Every area of the documentation outside of the Advanced and some of the Tutorials section are written from the perspective of a non-developer. They focus only on the tools that users would use such as the layout manager and menu editor.
We are always open to any contributions from the community. What would really help us tackle the documentation and perfect it is to get specific feedback about any pages or areas of the documentation that could use a bit more fleshing out and/or simplification.
If you can think of a method that breaks down Gantry in a more simplistic fashion, we'd love to incporate them into the documentation. Feel free to submit tickets at http://github.com/gantry/docs if there is a particular area of the docs that is a bit too over-the-head of the users, and we can certainly address them. You can also make changes directly using GitHub and we will merge them in so you can have credit for the contribution.
This feedback is invaluable, and I strive to make our docs as easy to follow as they can be. Thanks! - Ryan Matthew Pierson / Technical Writer / Buda, TX USA
-
-
-
- Ryan M Pierson
- Sr. Rocketeer
- Posts: 243
- Thanks: 164
- Technical Writer
-
Brian Shea wrote:
A simple install of G5 and Galatea gives me TWO template options for Galatea.
Why? Why do we need a separate 'Home - Particles' layout?
Those two template options are outlines, which is a fancy word for Joomla's common override system. One thing we've always done, since Gantry at least, has been to create a separate template override for the Home page since this page is so different than any other page on the site. It gave us the option to create a unique layout, as well as styling that sets it apart.
In Gantry, our name for this is Outlines. We gave it a different name because Gantry 5 is intended to be platform agnostic rather than specific. I will try to expand on this in documentation a bit more.
For now, this is the current base-level documentation of this concept: http://docs.gantry.org/gantry5/basics/terminology#outline
Brian Shea wrote:Why? Why 'take over' what was there prior to installation?
This was a decision made early on in development of Gantry 5 because initial testers found it too confusing or difficult to understand that the framework had to be active before the theme, and total beginners had a hard time with figuring out how to active a framework, or set a default override.
We always recommend not installing this straight away on a live server, but testing and setting up on a testing server first, then migrating. This recommendation is documented frequently in the docs.
Brian Shea wrote:What would help tremendously is to keep things simple. A template/theme is supposed to change the look of a site, NOT change the underlying concept of the CMS being used.
The only thing Gantry or a Gantry-powered theme changes is the look of the site. There is theoretically nothing you can do in the Gantry admin or with a gantry theme that will disrupt or change the way your CMS functions, handles data, or sees its data.
We don't even have data stored in the database (where possible) for this reason. The intention isn't to change anything about the CMS, but the way data is rendered on the front end.
Brian Shea wrote:Base Outline should be the basic default. Why Base Outline, Default, and Home - Particles?
Default could be anything you want. We just went with that naming scheme for simplicity. Base is where you set the settings you want used universally across the site. Default is the actual outline your new content and pages are set to by default, and home is assigned (in assignments) to your home page.
The idea here has some reasoning behind it, and I'd invite a member of our dev team to expand on it.
These are great questions, and I will be looking at how I can expand on their answers in documentation over the next week. Thanks for them! - Last Edit: 8 years 2 months ago by Ryan M Pierson. Reason: spelling
- Ryan Matthew Pierson / Technical Writer / Buda, TX USA
-
-
-
- Brian Shea
- Sr. Rocketeer
- Posts: 176
- Thanks: 18
- Web Management, Server Admin, Google Apps Service Provider
-
Ryan, what you have put together is fantastic from what it originally was. And I do see the simpled down parts.
And, after spending several hours of breaking down different aspects of G5 for myself, I can see where the confusion (and perhaps the resistance) may come from. All of the components are built right into the template, and a lot of cool features are done in the template 'framework' instead of the CMS plug-ins. While this is actually great, and mostly an expansion of the G4 'simple features', it is different from 'just a template'.
This is not complaining, as I am just observing where the source of the complaints might arise from.
While G4 was needed for the older templates, it was built as simply extra feature settings of the template. With G5, it's no longer a hidden framework. It's a full blown component managing many built-in features. But, it's a template? ?
In G4, we also needed other extensions/plugins. RokSprocket slowly became the super component for most of the other extensions (gallery, tabs, etc). But, it was still a 'component' to go to for editing a slideshow or special feature. And if we didn't need any of the extra functionality of RokSprocket, we didn't have to install it. (simple gallery plugins are too much for many of my clients, so RokSprocket was way over their heads)
Now, with G5, there are no extra extensions. They are built into the template. So, if I want to do anything that might have been done by RokSprocket, it's already installed... as 'features'. Two issues with this... first being that it's just a bunch of clutter for those that don't need it. Second issue is the disconnect from the 'extension' concept, causing confusion over where to edit what. Do I edit in content, in template, in extension, or a module? Wait, is that module in 'modules' or an 'module instance'?
Perhaps this type of super-feature-inclusion can be explained a little better?
Yes, it makes it easier for people new to Joomla (or WP or other) to have all these neat features included. It makes it less confusing when they don't have to search JED (extensions.joomla.org) for cool things. That's awesome. But, what of those that are vets of the CMS, very familiar and used to finding extensions that meet a specific need? Seeing all of these un-needed (for most) features seems to create a feeling of bloatware. I would assume the old-timers would be expecting to edit and tweak features of slideshows/tabs/lists/cool-stuff in special components, and not the template.
Again, this is not a bashing on the direction of G5. (I admit, I've voiced concerns before) This is my understanding of some of the differences that create a reaction.
How this can be explained better, I don't know. If inspiration hits me, I'd love to contribute, but, well, we know how that goes.
...oh, I have not watched any of the video tutorials, so if those cover a lot of stuff, then I missed it -
Website Hosting and Management
for the non-technical, non-geeks
G+ Page for Seven Sages , a Google Apps Authorized Reseller
-
-
-
- Anibal Sanchez
- Newbie
- Posts: 13
- Thanks: 2
-
Hi,
In my experience, "Particles" topic has been a huge concept since the beginning. With time, I have discovered how deep and clever they are designed and implemented into a "template".
In general, most templates have adopted Bootstrap 2/3 as an industry standard and created a library to simplify template development. On the other hand, Gantry framework has adopted PHP components and patterns to create a real engine for templates.
BTW: Grav is also a leap forward in the flat-file CMS area, implemented following similar practices. - Best Regards,
Anibal Sanchez
____________________________________
Extly.com - Extensions
-
-
-
- Henning
- Preeminent Rocketeer
- Posts: 29362
- Thanks: 954
- Volunteer
-
In Gantry 4 templates we often had big snippets of custom html in artciles and custom-html-moduls.
Those where hard to replicate and maintain and not flexible at all.
Particles give the option to create content with nice a UI-interface.
They almost work like a content construction kit.
They open the door to very individual designs and elements.
Creating those particles is very easy. Much easier than creating modules.
Even with Roksprocket the options with modules are limited. Partciles mean freedom.
-
Time to create page: 0.059 seconds