Our current docs are becoming slightly out of date and not keeping up with our development pace. The current docs system has a high latency and steep learning curve for maintenance, and it has started functionally and visually lagging behind docs for related technologies (see react, unity, ember, angular, ionic).
This proposal aims to accomplish the following three goals for our documentation:
Below is a formalized list of requirements that are proposed for the Cordova docs.
The following features must be supported by the Cordova docs.
The following features are nice to have in the Cordova docs.
Sphinx is a mature and complete documentation system written in Python. All documentation hosted by readthedocs.org uses Sphinx. Sphinx meets all functional requirements of this proposal.
Pros:
Cons:
Jekyll is a static site generator written in Ruby. It is used to generate the docs of React.js. It meets some functional requirements of this proposal.
Pros:
Cons:
JSDoc is a mature documentation system written in JS. It is used as a back-end to generate automated source code docs for many JS projects. It meets some functional requirements of this proposal.
Pros:
Cons:
The current Cordova docs could also be extended to meet the proposed requirements.
Pros:
Cons:
Sphinx (either with readthedocs.org or without) would provide a complete solution for Cordova's documentation needs. However, it would require a (hefty) migration.
A mix of Jekyll, JSDoc, and the current Crowdin pipeline would suit Cordova's documentation needs. The existing documentation can be migrated to such a system with only moderate effort.
This prior analysis was used to decide on a JS documentation framework. Currently no quantitative analysis has been made to compare the solution candidates, but one can be carried out if required.