Documentation is one of our key priorities here at Frontity and we want it to be the best possible resource for the community.
Since the formation of the Frontity Developer Relations team almost one year ago, Michael and I (JuanMa) have been analyzing and consulting with the rest of the team and with the community about how the documentation could be improved and made more effective.
After several months of work, we're excited to announce that we have revamped the documentation to bring you more helpful resources and improve your experience with Frontity.
In addition to the recently announced step-by-step tutorial, we've published a new API reference site and reorganised the docs across three different sites:
Before explaining these changes in detail, let us tell you more about the reasons behind them. If you can't wait to see what's new, feel free to jump ahead to this section.
Why are we making these changes?
The goal of the changes we've made is to provide you with the most useful information in the most appropriate context as and when you need it. The new structure will make it easier for you to understand and consume the information presented in the documentation, and will also make it easier for you to find and apply the knowledge in your own projects.
Following the analysis and the various conversations we had we detected that:
- We lacked a good tutorial that could guide any developer interested in learning Frontity through the process of creating a theme from scratch whilst also covering the most important features of a Frontity project.
- We needed to separate out two types of documentation that were mixed together in the same place:
- API Reference docs: these are more detailed and technical explanations that can be easily used as a reference when developing a Frontity project.
- Guides docs: these are practical and theoretical explanations that could help our users to fully understand the potential of Frontity and that could guide them in the development of their projects.
After arriving at these conclusions we decided to split the documentation across three different sites that represent the distinct purposes or functions that good documentation should fulfil, namely: tutorial, reference, and conceptual understanding.
Previously all the information was lumped together in one place, making it hard to find the precise bit of information that you needed, or to distinguish between what was intended to be conceptual understanding and what was intended to be reference.
What's new?
New structure with separate sections
The new structure of the documentation will provide you with three separate sections, each of them can be found under a separate sub-domain of frontity.org:
- Tutorial →
[tutorial.frontity.org](https://tutorial.frontity.org/) - Conceptual understanding / Guides →
[docs.frontity.org](https://docs.frontity.org/) - API Reference →
[api.frontity.org](https://api.frontity.org/)
1. Tutorial
Found under the tutorial sub-domain this is our recently published step-by-step guide. This is the site to visit if you're new to Frontity and looking to learn how to develop sites using Frontity, or if you've previously worked with Frontity but feel that your knowledge is fragmented or incomplete.
The tutorial teaches web development with Frontity in a progressive and sequential way. It is primarily a didactic resource. You can learn more about it in this blog post.
2. Docs / Guides
This section can be found under the docs sub-domain where all the documentation previously resided. This is where you should go if you want to deepen your conceptual understanding of how Frontity works and how a Frontity project should be implemented.
As well as theoretical information, such as Frontity architecture, you can also find some practical guides here. For example how to deploy a Frontity site or troubleshoot your Frontity project. Some practical how-to's will also be coming to this section in the near future.
In addition to the above we have here useful introductions to JavaScript/ES6 and React in case you need to get up to speed with these.
3. API Reference
The API Reference is where you go when you want to look up a specific piece of information that you need in order to implement your Frontity project in the most efficient and effective way. This section will primarily be used by those developers who know what they are looking for and need to find it quickly.
This section can be found under the api sub-domain. Read on to learn more about this newest addition to the documentation.
New API Reference site
Whereas the step-by-step tutorial is focused on learning Frontity, the focus of the API Reference is instead on providing technical information and detailed descriptions of the tools available for a Frontity project.
We've divided the content into four primary sections: CLI, Packages, Themes, and WordPress Plugins.
Frontity CLI
Almost every Frontity project will start in the terminal at the command prompt. This section is where you'll find comprehensive information about the commands, and the command line options, provided by the Frontity CLI that you can use to create, run and build your Frontity projects.
Packages
Packages are the building blocks of your Frontity project. They're NPM packages which implement specific logic required by the project. Included here are references for Frontity core, the source package (@frontity/wp-source), the router package (@frontity/tiny-router), amongst others.
Themes
In reality a Frontity theme is just a special instance of a Frontity package. At root everything is a package when you're working with Frontity.
However most developers working on a Frontity project will primarily be working on a theme. We have therefore afforded the built-in themes (@frontity/mars-theme and @frontity/twentytwenty-theme) their own dedicated section of the API Reference.
WordPress Plugins
In order to get the most from headless WordPress there will be times when you will want to add functionality to the backend server. At these times you will need to install a PHP-based WordPress Plugin.
Oftentimes Frontity plugins will extend the REST API to provide additional content that you can use in your Frontity project. Information on using and configuring these plugins in WordPress, and consuming the data in Frontity, can be found in this section.
We're not done yet...
This is just the beginning of several improvements we plan to add to the documentation.
Over the last year the DevRel team have been working on what we refer to as the "Frontity Learning Experience". Work on this led us to consider what might be the best way to explain and present the knowledge required to work with Frontity.
The result of this research was that we derived certain conclusions regarding what content was needed by Frontity developers, and what was the best way to structure it. The continuing implementation of these results will be the DevRel team's top priority during the current calendar year.
Keen to dig in? Great! Check out the new docs and let us know what you think of the new structure.
Contributions to improve the documentation are always welcome. The Frontity docs are housed on GitHub and you can suggest changes and improvements at any time by following these contributing guidelines.
Top comments (0)