- Status: Completed
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:
- add a search feature
- make contribution very easy
- set up automatic deployment
Below is a formalized list of requirements that are proposed for the Cordova docs.
The following features must be supported by the Cordova docs.
- "edit on github" buttons
- Can easily submit changes to the docs via a PR on GitHub by clicking on an "Edit this page" button or something similar.
- search
- Can search through the full text of the docs.
- doc versions
- Can browse and change docs for any Cordova version.
- localization
- Can easily translate the docs into and/or read the docs in different languages.
- API docs
- Can automatically get generated docs for public APIs (plugins, cordova-lib, cordova-js).
- analytics
- Can have analytics for the docs website.
The following features are nice to have in the Cordova docs.
- easy transition
- Changes to the docs inconvenience people as little as possible.
- good UI
- The UI for the docs is aesthetically pleasing, intuitive to use, and gets relevant information with as little friction as possible.
- free
- We don't have a budget outside of our own computing power and engineering resources.
- static
- The generated docs should be static files (unless we find a free hosted solution).
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:
- mature and used by many large software projects; many people know it
- feature-rich: search, referencing, internationalization, templating, generation, plugins, and many others
Cons:
- needs some knowledge of Python
- needs migration from Markdown to reStructuredText
- needs migration from Crowdin to Sphinx's own internationalization tools
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:
- mature and used for many static websites; many people know it
- integrates well with other tools
- has powerful templating for the output
Cons:
- does not have search or internationalization
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:
- mature and widely used; many people know it
- integrates well with other tools
Cons:
- does not have search or internationalization
The current Cordova docs could also be extended to meet the proposed requirements.
Pros:
- no migration required
Cons:
- does not have search or templating
- non-standard, so the learning curve remains
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.