RFP update and overhaul cordova-docs

[brodycj]

My understanding from Apache Cordova PMC discussions is that an anonymous donation was received for the purpose of improving our documentation. I think it should be enough to cover multiple months of full-time work if we can source the work in a strategically intelligent manner.

Issues have been piling up over the years. I would really like to see some things happen in the near future such as:

• review of all existing documentation to check for resolve items such as incorrect information, missing information, and any possible lack of clarity
• get automatic doc build working again (Automatic doc build is broken (Travis CI) #1035)
• add tutorials and guides for some common tasks such as:
  • using Cordova with tools such as Babel, Rollup, and Webpack
  • integration with some larger frameworks such as Angular, Vue, Preact, React, and Ionic
  • authoring plugins for Android, iOS, and Electron
• upgrade to use a super-modern documentation system such as Gatsby, JSDoc, etc.
• go through the open issues and get them down to a handful at the most (let's get them fixed please, avoid some other outcomes such as "invalid" or "won't fix")

It would be ideal if we could find a maintainer or similar kind of Cordova expert as well as a well-qualified technical editor who would have the time to do this kind of update and overhaul in the near future.

I would also very strongly favor an agile approach where we start with tasks of limited scope and limited cost. I really hope we can start to see some positive impact before burning too much of the budget.

/cc @DRuggeri

[dblotsky]

Hey @brodybits!

Here is the original proposal that shaped the site and docs as they are today: https://github.com/apache/cordova-discuss/blob/doc-improvements/proposals/ImprovedDocumentationGenerator.md.

JSDoc is a great option, and was originally proposed as the way forward (and would plug well into the Jekyll site). I don't remember anymore why we didn't follow through with using it, but I suspect it was just because most of the Cordova docs content is hand-written prose, not automatically generated specs.

[brodycj]

I have some more thoughts on this:

• I think we need to update all documentation, including plugins & documentation for contributors and maintainers.
• There may be quite a bit of investigation, testing, and interactive discussion needed to get it right.
• I think it would be ideal if we could include efforts to verify that all existing and updated documentation reflects the actual behavior.
• This kind of project should be done in an agile manner, with limited sprints starting with limited pilot phases, to avoid the risk of waste on incorrect priorities.
• Domain experts, ideally multiple Cordova maintainers, would be needed to help ensure we get this right.

JSDoc does seem to be the most well-known, stable, and JavaScript documentation system. I have seen some other nice frameworks such as gitbook and Docusaurus, recall seeing at least one case of maintainers just dropping support.

I am also thinking this would be the perfect time for us to get the ball rolling, before an economic recovery leads to higher costs and more limited expert availability.