openmainframeproject
Adding Documentation for software-discovery-tool
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.
@rachejazz , can I work on this issue and start with the basic structure for the documentation?
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)
Would it be best to create a new branch for this task, or how should I initiate it?
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
@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.
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!
@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?
I have some suggestions for the documentation:
- 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.
- We may have a section on the landing page that introduces SDT and outlines its key features.
- 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.
I have some suggestions for the documentation:
- 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.
- 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.
- 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.
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.