@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
API Reference
Besides this one, we also manage the following sites
2. Resources
2.1 Which syntax/format to use when documenting API Reference docs
Guidelines for API reference docs
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
Code Releases
Code <-> Documentation workflow
In the WIKI of the Docs repo is documented the Code Released workflow agreed w/ Dev team to document features after they’re released
2.3 What should be structure of a Feature Discussion to ease the documentation process after the release
How can we improve the FDs process? → Mario’s proposal
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?
Code <-> Documentation workflow → Yes, as agreed on January 2021
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
-
The
type: code release
issue is created in the API Reference repo
What do you think?