After gathering feedback and working on the mindmap for Frontity’s knowledge here you have the Documentation Structure 2.0 proposal we have for the new structure of documentation sites
Feel free to share your feedback as we’ll begin to apply these changes soon in our documentation site
You also have available the structure of the API reference site although there are no big differences compared to those same section in the current documentation site
Why Frontity from a Marketing/Product point of view. This diagram may be useful here
Features & Benefits
Comparisons
Foundational Concepts
Technical ideas that makes possible the features. This sections is not supposed to explain in detail each idea but point out and remark those technical ideas that makes Frontity different like:
logic is delegated in packages
packages are organized through namespaces
Frontity creates a final app as the sum of packages used
Frontity uses 4 core elements to orchestrate packages:
state, actions, roots & libraries
Frontity Modes
Overview of the ways Frontity can be used (Decoupled Mode, Embedded mode, Serverles,… )
Browser Support
3- A Frontity project These are the first things a developer will face in its Frontity project This section should cover topics recurrently asked from the community
Anatomy of a Frontity Project
Files Structure & Settings
Packages & Themes
Essential Packages: theme, source, router
Settings
frontity.settings.js
Styling
Styles with CSS-in-JS
Standard Styling with Global CSS Files
CSS Libraries and Frameworks
Flow of data
setting REST API
data: links info
entities
Normalization of data: Why
Development Stages
Development
Production
The Build Process
4- Core Concepts
Frontity Core
State
Actions
Roots
Libraries
Packages
Namespaces
Essential Packages: theme, source, router
Other built-in packages: html2react, components, hooks
Working with Gutenberg Blocks in a Frontity project
Applying html2react processors
11- Guides
Find some quick guides oriented on how to build things with Frontity
This will evolve into a guides page, where guides will be able to be found through tags and search
TypeScript Guide
How to work with Slot and Fills
Understanding Mars Theme
Keep Frontity Updated
How to work with packages
Install a new Frontity package
Creating a Functional Package
How to work with handlers
How to share your Frontity Project
Troubleshooting guide
Setting your development environment
Accesibility Guide
Comparison guides
There are some decission making docs that we should offer somewhere. Until we don’t have a better place we can start offering this content as Blog Posts or as Docs Guides
This should cover the advantages of using Headless, and React over a traditional WP installation
Explain more in detail that Frontity is an Open Source and how users can contribute
Specific details about code contribution should be provided in the main repository (design principles, workflow, testing…)
How to contribute?
Contributing Guide
Design Principles
FAQ ?? Not sure about having this section or the questions that should contain.
Hey, great work guys!! I think these structure is much more clear then the one we currently have
I don’t have much else to add right now. I am sure more ideas and feedback will come up at a later stage for each of the sections, but this new structure makes a lot of sense to me as it is.
By the way, I guess you can reuse a lot of the content that Reyes is creating for the white paper for some of the sections that explain Frontity
Hi @juanma.
Great job !
So far, I used docs.frontity.org combined with youtube channel to improve my skills. But now with the forthcoming tutorial site that will be easier for me.
I’m eager to read it.
Thanks
I’d just like to mention a couple things that I’d like to see us have in the new docs (This is mostly applicable to the API docs):
Switching between documentation versions (so that the docs for frontity v@1.4 for example include don’t include the features that were added in the v@1.5)
Include an “Added in [frontity version]” for specific APIs and maybe even have a “History” table for a particular API like in node.js docs.
This makes is easier to understand when some feature was made available and if a user needs to upgrade in order to use it (if they are on an older version of frontity).
Hey @juanma thanks for putting this together. And sorry for my late answer.
Great Job, I love the new structure, and I think that it’s going to make things much easier.
I don’t have any suggestion that requires a major change on your proposal.
Great question Reyes.
I see that under the 3. A Frontity project > Anatomy of a Frontity Project section, there’s going to be an explanation of the Packages and Themes. Not sure if that’s going to be enough. My suggestion is that we create a whole section like Performance and SEO but for Themes and Extensions. The main reason is that we should explain how to use and how to create themes and extensions for Frontity, and that’s not going to be covered in the API site.
Other small things I’ve noticed:
To me, it looks like the section 10- WordPress could just be part of the 11- Guides section. As it looks like it’s only going to contain a couple of guides on how to do some things on WordPress.
Does it make sense to move the Frontity Modes section from 2- Understanding Frontity to 7-Deployment? Or maybe give a first explanation in the Understanding Frontity section, and afterwards explaining the technical details on how to handle the different architectures in the 7- Deployment section?
I think that the 7- Deployment section needs to cover also all the things related to WordPress instance. Specially the complications derived from the “Decoupled architecture” (What theme should I use? How do I handle redirections?..)
I don’t see how can we implement this with the current platform we have as gitbook only allows creating these variants per site and not per section, and as we’ll different packages documented under api.frontity.org I think this cannot be done with the current platform
Besides this, I’d also like being able to have this in the docs. So we’ll take into account when we look for another platform for the docs in the next quarters
Yes, this is something that I think we can start doing. It will require more effort when creating documentation but I think it will be very useful for the community.
I think you’re right. This topic is important enough to have its own section
We consider there will be more info to be documented related to WordPress that will be easier to locate on its own section.
Some of the sections can be considered as a group of guides for a specific topic, but until we don’t have a proper guides site where each guide can be tagged, searched and easily located, we think it’s best to group these related info (guides and more) in specific sections that we consider will be frequently looked for.
Yes, that’'s exactly the approach, Provide an introduction (an overview) in Understanding Frontity and then provide the details later, but in this case the details will be provided in the Architecture section (and not in the Deployments section)
This info could be in the WordPress section and reference them from any Architecture or Deployment explanations
That is a great idea. Actually, maybe we should start doing so in our TSDocs as well so it is easier to add it to the docs. Which, by the way, WordPress does it with the @since tag. It is not going to be that easy but we can talk about it.
@pablo Regarding this, I think the right place to explain this is Core Concepts > Packages
I’ve added this idea of explaining “how to use and how to create themes and extensions for Frontity” there
