[User Story] Improve Balsamic documentation

[ivadym]

Need

• As a user, I have noticed confusing parts in the documentation that need urgent improvements for a better experience. I suggest clarifications to enhance usability.
• As a Balsamic developer, I want our documentation to be written in Markdown instead of reStructuredText (rst) so that it's easier to read, write, and maintain.

Suggested approach

1. Clarify installation instruction and requirements.
2. Improve short tutorial. 2.1 Update outdated steps. 2.2 Include practical examples and case studies that demonstrate effective use of Balsamic in real-world scenarios.
3. Improve detailed documentation. 3.1 Group shared documentation. 3.2 Divide variant calling, filtering, and annotation into separate workflows. 3.3 Clearly indicate which files are generated at different stages of the pipeline, distinguishing between raw, research, and clinical VCFs.
4. Ensure the method description is up to date.
5. Simplify and remove redundant information from Tools and Software and References sections.
6. Enhance and Restructure the Development Guide: 6.1 Define contribution guidelines. 6.2 Specify coding guidelines.

Considered alternatives

Deviation

No response

Risk assessment

• [ ] Needed
• [X] Not needed

Risk assessment link

No response

System requirements assessed

• [X] Yes, I have reviewed the system requirements

Requirements affected by this story

No response

SOUPs

No response

Can be closed when

• [ ]

Blockers

No response

Anything else?

No response

Need

Certain areas of our documentation require (urgent) improvements and clarifications to enhance the user experience. I would also like for us to move away from rst and use markdown.

Suggested approach

1. Clarify installation instruction and requierements.
2. Improve short tutorial. 2.1 Update outdated steps. 2.2 Include practical examples and case studies that demonstrate effective use of Balsamic in real-world scenarios.
3. Improve detailed documentation. 3.1 Group shared documentation. 3.2 Divide variant calling, filtering, and annotation into separate workflows. 3.3 Clearly indicate which files are generated at different stages of the pipeline, distinguishing between raw, research, and clinical VCFs.
4. Ensure the method description is up to date.
5. Simplify and remove redundant information from Tools and Software and References sections.
6. Enhance and Restructure the Development Guide: 6.1 Define contribution guidelines. 6.2 Specify coding guidelines.

Can be closed when

• [ ] Agreement on the new documentation structure.
• [ ] Transition from using reStructuredText to markdown.
• [ ] Fix Balsamic links in Atlas documentation.
• [ ] ...

Additional context

To prevent duplications, it is essential to create a cohesive documentation structure that aligns between the following sources:

• Atlas
• Order portal

[ivadym]

@Clinical-Genomics/cancer:

I've refined this issue. Improve Balsamic documentation v11 to clarify the differences between raw, research, and clinical VCFs was the original one. I think if we split the tasks here, we can get it sorted out pretty quickly.

[pbiology]

Excellent part of Release 14. It's something one can improve when waiting for other things