Clinical-Genomics
[User Story] Improve Balsamic documentation
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
- Clarify installation instruction and requirements.
- 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.
- 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.
- Ensure the method description is up to date.
- Simplify and remove redundant information from Tools and Software and References sections.
- 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
- Clarify installation instruction and requierements.
- 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.
- 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, andclinicalVCFs. - Ensure the method description is up to date.
- Simplify and remove redundant information from
Tools and SoftwareandReferencessections. - 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:
@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.
Excellent part of Release 14. It's something one can improve when waiting for other things
