I think it looks great, I have only noticed one thing that I think we should all agree on.
In TSDocs or in Documentation, when describing a method, I think we should be adding the () after the method name. Right now, we write it like (examples from current TSDocs):
An object that will be used in each call to the REST API when using actions.source.fetch with the default handlers.
Usually returned from api.get, but can also be the one returned by fetch.
Especially in the second example, it might not be clear to a new user that get and fetch are both methods and not some kind of getter or flag.
We’re not using prettier for code examples in markdown files. But I think we should.
We should add a prettier configuration file so we all use the same prettier configuration in the docs.
Which one are you using for frontity code?
As suggested by @mmczaplinski in Documentation 2.0 Structure maybe we could start doing adding a @since tag in our TSDocs for reference of when a feature/API was added.
WordPress does it with the @since tag. For example:
/**
* Checks if a block can be read.
*
* @since 5.0.0
*
* @param WP_Post $post Post object that backs the block.
* @return bool Whether the block can be read.
*/
In our case, it is not going to be that simple, because we don’t know the exact version that is going to be next, depending on the type of bump (minor or patch).
One idea would be to populate it with a NEXT tag, for example, and run a script that replaces all the NEXT tags with the bumped version of each package before the release.
We commit this:
/**
* Do something.
*
* @since NEXT
*/
And a script does a commit before the release, once the package.json files have been updated to replace all the @since NEXT found with the package.json versions:
/**
* Do something.
*
* @since 1.13.1
*/
Maybe to not overengineer it we could use an @after tag and add the current version.
For example, this means that this API is not available in version 1.13.1 or below. It is not as nice, but the final information is the same.
I think maybe it’s not even worth automating right now, because it might be more effort than it’s worth at the moment and it would be easier to just update the @since tags manually after a release.
I think that the Final Implementation should in almost all cases be sufficient to create documentation based on it. In fact, I have lately used mostly the same text in both the github issue of the docs and the Final Implementation, for example when implementing state.source.url:
Thus, I propose that we centralize all the details in the Final Implemention post that would normally go into the github issue in the Docs repo. The issue in the github docs should then include just:
the link to the PR
the link to the FD
any (optional) notes to the DevRel team about the feature that are beyond the scope of the FD. Those may be something like: “Let’s create a new section in the docs for this feature”, for example.
Totally agree @mmczaplinski Our end goal should be to improve the Final implementation post, with everything needed, so it is enough to fully understand each feature.
What is the status of this? Is this information available for all the methods yet? Is this somethings that is going to be applied gradually from now on?
Regarding API Reference documentation I finished checking what is going to be the new site for these docs → https://api.frontity.org/
For that review I have applied prettier to all the docs and included that in the pre-commit hook (so prettier will be automatically applied on every commit)
I have also created in the WIKI some Guidelines for API reference docs with the criteria I’ve followed to document every piece of information (syntax, arguments, types, is mandatory, …). These guidelines takes into account the constraints we have for working with gitbook.
Any feedback on these guidelines (how to properly document API) will be appreciated
@juanma now that the DevReal team is going to lead the development of the starter themes, I have a question for you: Will you use the same TSDocs standard that we use for the rest of the Frontity packages, or do you prefer to use another comment format/standard?
I am asking because we have our eslint configured to require TSDocs for the theme files, and each time we edit a file we need to add proper TSDocs for the whole file (we are doing it that way to add TSDocs to our codebase progressively). So if you don’t plan to use TSDocs for the starter themes, it doesn’t make sense that we spend time with that, does it?
Juanma has decided that they are going to use TSDocs in the themes, so we don’t have to modify what we do.
Also, I have opened an issue to remove all the React imports from the themes (and our packages), but we agreed that we will ignore the Eslint TSDocs errors for that PR, to avoid the need to add TSDocs to all the theme files at once.
@santosguillamot and I thought this morning that maybe it would make more sense to not open the “doc issue” in each of our PRs, but once all the PRs of that feature have been merged and we are writing the Final Implementation (and creating the demo video) in the FD.
We think we can make a better summary of the feature and the things that need to be documented as part of the Final Implementation, and it would be much more useful for you.
@juanma, @mburridge: At some point @santosguillamot and I proposed to be the ones helping you to document the next features because we want to understand what you need.
If you still want, we can do that for the Google Ad Manager package.
So should we be approaching one of you two and not the developer who implemented the feature when we want to document a feature and need more clarification/information?
@luisherranz@SantosGuillamot@mburridge I’ve tried to wrap up here the resources and conversations we’ve had regarding the documentation, specially those about the workflow for documenting new features
1. Documentation Sites
The main site affected by features documentation is
in the WIKI of the API Reference docs repo there are the Guidelines for API reference docs with the criteria followed to document every piece of information (syntax, arguments, types, is mandatory, …). These guidelines takes into account the constraints we have for working with gitbook.
2.2 What is the workflow to follow to document a new feature after it’s released
Regarding this conversation, the most interesting proposal from a documentation point of view is having a Final Implementation section in every Feature Discussion that has been released
From the Final Implementation section proposal I’ve marked w/ those that are most interesting for DevRel for features documentation
Final implementation
Pull Request → Link to the PR where it was implemented.
Requirements → For example, for the @frontity/yoast package, you have to install the Yoast plugin ^14.0
Functionalities → List of the final functionalities that were included in the final implementation, with a detailed explanation of each one: how it works, how to use it (install a package? add a new setting?) and a code example/screenshot/quick video if relevant.
Out of Scope → List of the functionalities that were finally discarded or slated for a future time. Until we finish the implementation this may change, so I think is good to do a recap here.
API changes
Backward compatible changes→ List of the changes that are backward compatible.
Breaking changes → List of the breaking changes and how to migrate your old project.
Deprecated APIs → List of the deprecated APIs.
Technical explanation → How the feature was implemented. We explain the code
Demo → Full video explaining how to use the feature and its functionalities. This can be added afterwards. We could even include a CodeSandbox like we did with the wp comments.
2.4 Are we going to use TSDocs for documenting the code?
This will affect anyone modifying the code of the themes/packages as these comments are required to pass the PR checking and being able to merge the PR’s
From here we can have a meeting if you want so we can clarify some final points.
For me the key things that would help DevRel to document new features are
The creation of. The Final Implementation section and content suggested by Mario Following this workflow:
The PRs of that feature have been merged and the Feature has been released
The Final Implementation section is added to the FD
Our end goal should be to improve the Final implementation post, with everything needed, so it is enough to fully understand each feature.
I think this will simplify the understanding of the features to document them
those that are most interesting for DevRel for features documentation
The creation of. The Final Implementation section and content suggested by Mario
The PRs of that feature have been merged and the Feature has been released
The Final Implementation section is added to the FD
The