Develop consistent method for capturing FAQs / common errors across all PDS repositories

[jordanpadams]

💡 Description

Looking for a standard way to capture FAQs and common errors for each of the components of the system.

These are often dynamic and we want to be able to change these quickly based upon some comments from users, so we do not want this to be in our online documentation where we have to tag a new release and deploy the docs anytime something new comes up.

Let's use this thread to come up with some ideas.

a. We use each repos Wiki to capture these - PRO - it's easy to do and consistent across repos. CON - people don't really notice those wikis being there, and the revision history isn't readily accessible (you can checkout the wiki repo but just not as clean)
b. We have an FAQs.md at the top of every repo - includes both FAQs and a separate section for Common Errors, we just update this file and link to it from our online docs.
c. We use each repos Github Discussions - would encourage folks from the community to potentially participate, but not as refined as an explicit file or wiki page curated by the repos committers/PMC.

[kgrimes2]

I don't think revision history is too important for an FAQ page. I like (a), but like you said, people might not know to navigate there.

Putting a link to the FAQ wiki from the README would work great. Could have a toolbar at the top of the README linking to the FAQs, release notes, and the like, à la readme.com.

[jpl-jengelke]

I would vote for the Wikis but link to them from the Changelog, Release Notes and/or README. That way the FAQ floats with the repo and isn't tied specifically to the release. FAQs definitely evolve with more information and can often be used to resolve concerns from multiple releases (consider app login or installation questions).

[nutjob4life]

Anything but Zendesk

[jordanpadams]

@nutjob4life @jpl-jengelke @tloubrieu-jpl I tried this here: https://github.com/NASA-PDS/pds-registry-app/blob/main/docs/support/faqs.md . it isn't pretty but it was easy to update...

[jordanpadams]

could obviously easily move to wiki if we think that is better...

[nutjob4life]

GitHub Discussions maybe not so good for release notes but seem pretty well suited for FAQs, no?

[jpl-jengelke]

Personally, I like the wiki for FAQs. ... https://github.com/NASA-PDS/pds-registry-app/wiki

[jordanpadams]

@nutjob4life @jpl-jengelke I kind of like the discussions... https://github.com/NASA-PDS/pds-registry-app/discussions

I saw we start there to encourage community engagement, and from there, we can switchover to FAQs / Common Errors wiki page if needed.

thoughts?

[nutjob4life]

Yeah! Pinned Q&A's in discussions are essentially FAQs!