The preview of the Octane version of Ember is coming quickly, and with all these unbelievable new options comes numerous documentation. Since this requires coordination of many transferring components, we need to define the method we’re taking, and outlining some ways in which the neighborhood can contribute.
Preparation
In an effort to put together for the brand new version, the Studying Core Staff hung out determining how one can finest transition the present docs in such a method that was according to iterative innovation.
One of many objectives of bettering the guides on the whole was to enhance the educational circulate within the guides (see RFC #431). As such, we decided {that a} change to the desk of contents was so as.
Updating the guides
As per the standard commonplace, we have now deliberate out this work to have the ability to full it in an iterative style. This was notably vital as a result of we’re updating guides as new options for the Octane launch are merged into Ember.
Phases
That is roughly the deliberate phases of the documentation work for the Octane version of the guides.
Part 1, MVP: (see Monitoring problem)
- Create octane department of the guides repo for this work
- Reorder the desk of contents (as per RFC #431)
- Add in placeholders for any new sub-sections
- Add or replace content material in every sub-section (prose, code samples, and so forth) https://github.com/ember-learn/guides-source/points/394
- Evaluate, edit & re-arrange sub-sections earlier than preview launches
- Add re-direct URLs and take away outdated content material
- Take a look at/Evaluate to verify every thing works as supposed
Then the Octane guides will probably be thought-about in MVP standing and we are going to transfer ahead to the following section, which can embody the entire sections that have been recognized within the desk of contents RFC however weren’t included within the MVP.
By all of those phases, a preview of the Octane version guides will probably be used to make sure that the documentation is staying on monitor with the supposed options.
Whereas new content material is being written and older content material is being up to date, no present content material will probably be utterly deleted. Solely after we have now totally reviewed the content material and added the re-directs will outdated content material be eliminated. Which means that within the interim, some content material could also be accessible if the consumer has the URL, but it surely will not be linked from the desk of contents.
Challenges
As with all formidable endeavor, there are some associated challenges. Listed here are just a few we’re at the moment going through:
- Updating guides content material for the Octane function set and defaults
- The variety of sub-sections for every information part
- Dealing with redirects for outdated content material in a method that will not break present deprecation messages
We count on to work via these challenges and have a course of in place to deal with them, however we must always have a shared consciousness that our method could also be tweaked as the following month goes on, to deal with these points.
How one can assist
We count on that the neighborhood will probably be prepared to submit PRs to assist make the documentation higher–from checking for spelling or grammar errors, to including code samples, and much more ambitiously, writing some prose.
Because of our infrastructure upgrades in 2018, we’re well-positioned to simply accept neighborhood participation within the documentation effort. Please see the open points within the guides supply repository and tell us within the #dev-ember-learning channel (on Discord) if you want to work on a difficulty.
All PRs for this ought to be made in opposition to the octane department of the guides repo and will comply with the common requirements for pull requests to documentation, crucial being one problem per pull request.
Way forward for Contributing
The Studying Core Staff is working to make it even simpler to contribute. We’re planning higher contributing guides than we have ever had earlier than, and you’ll be a part of this course of! We’re including a Contributing part to the web site–take part in shaping this content material by serving to evaluate/touch upon RFC #446.
