Create documentation platform for using the PDC

[reefdog]

This is a placeholder issue for more of an Epic:

While pieces of the PDC are documented, either within code, within repository Markdown files, or within generated artifacts like the Swagger API spec, integrators and some users would benefit from more centralized, comprehensive, and formatted documentation. This should be based on an actual documentation-focused CMS such as Docusaurus, although the gold standard for API reference documentation is surely Stripe's (which, interestingly, is distinct from their general docs).

This would be a new repository, deployed to its own domain such as docs.philanthropydatacommons.org.

[slifty]

@kfogel I'm putting this in Phase 3 for discussion; it seems to me that if one of our P3 goals is having a third party build a robust client against our service, it might be the right time to put some energy into the ideas captured in this issue.

[kfogel]

Noting the connection between this and service-#2085.

[kfogel]

@jmergy and I have come up with a plan:

The main PhilanthropyDataCommons.org web site, a WordPress site, will be the canonical publication place for all documentation that's in any way user-facing. That includes most of the Markdown files currently in our repositories. In fact, here is the complete list I believe:

• Everything in https://github.com/PhilanthropyDataCommons/service/tree/main/docs/
• https://github.com/PhilanthropyDataCommons/meta/blob/main/ARCHITECTURE.md
• https://github.com/PhilanthropyDataCommons/meta/blob/main/POLICIES.md
• https://github.com/PhilanthropyDataCommons/front-end/blob/main/docs/SENSITIVITY_CLASSIFICATIONS.md
• ...I think that's it, but take a look around for other stuff. For example, the documentation Jesse is currently writing about using Google authn as a 3rd-party IDP would go on this list too (but it looks like he's integrating it into an existing doc already on the list anyway).

If there's an easy plugin or other WordPress functionality to handle this "for free" (Markdown -> WP Plugin -> main site), such that we can maintain the source files in the repositories as we currently do, then great. If not, let's just do the transition and then maintain them in WordPress after that.

Some reorganization or recategorization of the files, or of content within/across the files, may happen along the way in this process. Let's start from what we want the audience to see on the WordPress site and work backwards from that.

[yshng]

Sounds like the next two steps per meeting with @kfogel are:

(1) Review and structure the existing documentation with respect to audience and topic
(2) Get access to a WP sandbox and implement WP plug-in that can auto-publish markdown files from some repo, for example https://github.com/vaakash/git-it-write

[kfogel]

Update: we're going to use the staging WP site for the upcoming new PDC web site for this -- no need for a separate WP instance.

[yshng]

It looks like the main stumbling block right now with automatic publishing is that several of the Markdown files contain mermaid.js diagrams that are transformed into <pre><code> blocks by the publishing plug-in. With some human intervention, these diagrams could be transformed into mermaid blocks in the Gutenberg editor (I believe), with the MerPress plugin, or we could use image files which the plugin is built to handle. That would just be an extra step of generating the image for the maintainers.

[kfogel]

@yshng Oh, I see. Well, the generating of the images can be automated, I presume? I mean as part of our publication process.