search

odk-x / tool-suite-X

ODK-X Tool Suite Project roadmaps, issue queue, release notes and wiki.
https://www.odk-x.org
Apache License 2.0
25 stars 41 forks source link

Documentation: Improving Accessibility and Clarity for Contributors through TLDR and FAQ's #488

Open obooks29 opened 4 months ago

obooks29 commented 4 months ago

Users, especially those who are new to Opensource projects often struggle to grasp its purpose, what to do and where to find assistance.

Although documentation and a community chat are available, users are frequently overwhelmed by the volume of information and numerous links within the documentation. As a result, they may become lost or more confused.

While there is a community chat, users must wait for someone with the perfect answer to respond to their questions or clarify their doubts and that sometimes take a whole lot of time as most contributors are new also.

To address this issue, I want to propose adding TL;DR summaries and FAQs to each document and I will like to work on this.

Can you assign this to me @wbrunette @Redeem-Grimm-Satoshi

wbrunette commented 4 months ago

@obooks29 I think FAQs are a good, not sure how TL;DR summaries would work, but willing to see. @elmps2018 thoughts? @obooks29 I think you start and see what you come up with.

elmps2018 commented 4 months ago

I think I am a bit confused on how this would work for each document - what is meant by document here? For TL;DR summaries, since these are technical documentation, the detaisl are important. A different approach could be to consistently document "Purpose of this page" or something similar at the top in a box, but there are a LOT of pages. For FAQs, we already have a troubleshooting page.

So happy to take a look at perhaps an example mock up but would want to think about this and discuss with PMC a bit before scaling.

obooks29 commented 4 months ago

I already started. Thank you so much.

obooks29 commented 4 months ago

I think I am a bit confused on how this would work for each document - what is meant by document here? For TL;DR summaries, since these are technical documentation, the detaisl are important. A different approach could be to consistently document "Purpose of this page" or something similar at the top in a box, but there are a LOT of pages. For FAQs, we already have a troubleshooting page.

So happy to take a look at perhaps an example mock up but would want to think about this and discuss with PMC a bit before scaling.

What I meant by document is each page.

I understand your point and I agree that the content is technical however, providing a tl;dr summary at the top of each page can help users quickly grasp the purpose and key points without getting overwhelmed by the detailed content. This will help users navigate through the documentation more efficiently and find the specific information they need.

Where users are confused, they can clarify their doubts with the FAQ on the page. If this is unnecessary I will remove it. I will also take a closer look at the troubleshooting to see how best to adapt it.

I've already begun implementing this and will continue to refine it to ensure clarity and usability.

Thanks for the help @wbrunette @elmps2018