Open brodycj opened 4 years ago
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.
I have some more thoughts on this:
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.
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:
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