search

NASA-PDS / software-issues-repo

Issue tracking repository as a centralized entry point for general PDS software bugs and feature requests.
Apache License 2.0
0 stars 0 forks source link

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

Closed jordanpadams closed 2 years ago

jordanpadams commented 2 years ago

💡 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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

Anything but Zendesk

jordanpadams commented 2 years ago

@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 commented 2 years ago

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

nutjob4life commented 2 years ago

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

jpl-jengelke commented 2 years ago

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

jordanpadams commented 2 years ago

@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 commented 2 years ago

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