search

openmainframeproject / software-discovery-tool

Software Discovery Tool
Apache License 2.0
31 stars 40 forks source link

Adding Documentation for software-discovery-tool #119

Open pratham1729 opened 1 year ago

pratham1729 commented 1 year ago

As I discussed with @pleia2, we should have a documentation page for the software-discovery-tool, like a readthedocs page, something along the lines of https://dagger-docs.readthedocs.io/en/latest/?badge=latest, this is a project in which I had contributed majorly on the documentation.

I'll be using sphinx (https://www.sphinx-doc.org/en/master/) to create the documentation and ReadTheDocs (https://readthedocs.org/) to host it.

@pleia2 @arshPratap kindly look into it and assign this issue to me as I would like to work on it.

Apurv428 commented 4 months ago

@rachejazz , can I work on this issue and start with the basic structure for the documentation?

pratham1729 commented 4 months ago

hi @Apurv428 , i had some plans for this issue last summer when i opened it, as i've mentioned in the description, feel free to discuss anything if you want to (i've since been busy and forgot to take it up)

Apurv428 commented 4 months ago

Would it be best to create a new branch for this task, or how should I initiate it?

pratham1729 commented 4 months ago

yes you should create a new branch, but only start work when the issue is officially assigned to you by @rachejazz @pleia2,

also do take a look at how to write rst files and docstrings for python documentation

rachejazz commented 4 months ago

@pratham1729 @Apurv428 for this round I'm stopping assigning people issues since I've noticed assignee abandons the issue for months together. To get approvals, please send PR requests.

Ash-2k3 commented 4 months ago

Hi @pratham1729, I'd like to know more about this issue ? Can you please provide us with more details like, what are the things we are supposed to add to the documentation ? Thanks!

Apurv428 commented 4 months ago

@rachejazz I have created a PR with the basic setup. Could you please let me know about the necessary additions and requirements for the documentation?

Apurv428 commented 4 months ago

I have some suggestions for the documentation:

  1. Do we have any video resources available that demonstrate the functionality of SDT? It could be beneficial to consider incorporating such content into our documentation for enhanced clarity and comprehension. Additionally, in our installation instructions, we can categorize it based on the respective operating systems, rather than amalgamating instructions for Ubuntu and SLES. This approach may streamline the installation process and improve user experience.
  2. We may have a section on the landing page that introduces SDT and outlines its key features.
  3. Additionally, including a FAQ section could prove valuable for addressing common queries and enhancing user understanding. These additions would provide visitors with essential information about SDT and streamline their navigation on the platform.

I'd love to hear any thoughts on these suggestions.

pleia2 commented 4 months ago

I have some suggestions for the documentation:

  1. Do we have any video resources available that demonstrate the functionality of SDT? It could be beneficial to consider incorporating such content into our documentation for enhanced clarity and comprehension.

We don't, but we could create an issue around it as a wish list item if someone with video tutorial skills wants to give it a shot.

Additionally, in our installation instructions, we can categorize it based on the respective operating systems, rather than amalgamating instructions for Ubuntu and SLES. This approach may streamline the installation process and improve user experience.

The reason for the current flow was that some steps are the same across distributions, so we didn't want to have duplicate instructions written and maintained. That said, even I have found that the current version doesn't flow well, and having to skip through instructions on SUSE in favor of Ubuntu instructions caused me to sometimes miss steps. We should see if we can find a middle ground.

  1. We may have a section on the landing page that introduces SDT and outlines its key features.

Sure, this is where that video may be helpful too. But this does demonstrate a split between the user documentation and development/deployment documentation. Most of the documentation we have is focused on folks who are developing for and running this tool. We'll need to be clear who the documentation is for.

  1. Additionally, including a FAQ section could prove valuable for addressing common queries and enhancing user understanding. These additions would provide visitors with essential information about SDT and streamline their navigation on the platform.

We do have FAQ, but I guess they're too well hidden to be useful :laughing: We should integrate them into the documentation.

Live: https://sdt.openmainframeproject.org/sdt/faq Source: https://github.com/openmainframeproject/software-discovery-tool/blob/master/src/static/js/views/faq.html

But again, we'll need clarity that these are user FAQ, not developer/deployment FAQ.

Apurv428 commented 4 months ago

After reviewing several documentation sources, I've noticed that many of them provide detailed information about the tool along with guidance for users, developers, and other stakeholders. It's akin to an all-in-one platform. For instance, take a look at https://docs.scrapy.org/en/latest/. The documentation there is extensive, covering a wide range of topics. Perhaps we could extract the most crucial elements from sdt tool and its existing documentation for maximum benefit.

Apurv428 commented 4 months ago

Should I do the FAQ section for the doc?