This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- INCF
- Technical writer:
- hq
- Project name:
- LORIS training docs for open reproducible neuroscience
- Project length:
- Long running (5 months)
Project description
I. Abstract
The Longitudinal Online Research and Imaging System (LORIS) is a web-facing project management platform for neuroimaging research,supporting several Open Science initiatives. Documentation plays an important role in LORIS. Specifically, documentation helps LORIS users and developers to understand software details so that they may better use the platform or contribute to the software development. Meanwhile, LORIS documentation should also be updated. This project aims to help LORIS to improve its documentation.
II. Current State
LORIS currently uses Github Wiki, Read the Docs and the LORIS.ca website to host all the documentation. Specifically, LORIS GitHub Wiki hosts the largest amount of LORIS documentation, and additional LORIS tutorials, presentations, user guides and walk-throughs are hosted in a variety of platforms . The current LORIS documentation provides guides for LORIS developers and users, but it could benefit from further development and organization, especially in documentation updates and improvements in technical details.
III. Benefits to Community
By improving LORIS training docs for open reproducible neuroscience, researchers and developers would benefit from a more user-friendly tool, to improve data collection in their studies. Specifically, the project may update and improve LORIS installation/setup documentation, as well as end-user materials providing training for new users. Moreover, the project will aim to help to migrate and to update documentation from LORIS GitHub wiki to Read the Docs. Meanwhile, the project may provide a database diagram to communicate data relationships and improve architecture visualization. Finally, this project would update and improve content introducing people to LORIS, its open science context, and its use cases.
IV. Personal strengths for the project
Over the past few years, I have participated in several technical projects through which I have developed a strong background in technical writing. Specifically, I was responsible for documentation writing in multiple past team projects and I believe that I have enough experience in the use of technical writing tools such as Read the Docs, Sphinx, Mkdocs, markdown, LaTeX etc. Meanwhile, my previous teaching experience in STEM courses has also improved my skills in technical communication. The LORIS training docs for open reproducible neuroscience projects with INCF would be a great opportunity for me to apply my technical writing techniques to LORIS. Moreover, I am very interested in the field of neuroimaging and I have been trying to find opportunities to apply my technical knowledge to this field. The LORIS training docs for open reproducible neuroscience projects with INCF would be a valuable experience for me.
V. Deliverables
- Migrate and update current LORIS documentation
- Review, update and improve LORIS installation/setup documentation, and fill gaps in end-user materials providing training for new users
- Help generate a database diagram to communicate data relationships (e.g. subject, study visit) and improve architecture visualization
- Help update and improve LORIS API documentation
- Help update and improve content introducing people to LORIS, its open science context, and its use cases, involving multiple media formats
VI. Timeline
Community Bonding (August 17 - September 13) a) Complete familiarization with LORIS software and the team workflow. b) Review, update and improve LORIS installation/setup documentation.
Week 1 (September 14 - September 20) Update and migrate LORIS documentation from GitHub wiki to Read the Docs.
Week 2 (September 21 - September 27) a) Review current LORIS end-user materials. b) Start to fill gaps in LORIS end-user materials providing training for new users based on current documentation.
Week 3 (September 28 - October 4) Finish gaps filling in LORIS end-user materials providing training for new users.
Week 4 (October 5 - October 11) a) Comprehend current LORIS database architecture. b) Start to implement the database diagram for the LORIS platform.
Week 5 (October 12 - October 18) a) Finish the LORIS database diagram generation task. b) Review current LORIS API and start to help improve the API documentation.
Week 6 (October 19 - October 25) Continue to work on LORIS API documentation improvement.
Week 7 (October 26 - November 1) Finish improvement on LORIS API documentation.
Week 8 (November 2 - November 8) Review current content introducing people to LORIS and start to update and to improve the open science context.
Week 9 (November 9 - November 15) Finish updates and improvements of open science context in the content of introducing people to LORIS.
Week 10 (November 16 - November 22) Help update and improve part of use cases in the contents introducing people to LORIS.
Week 11 (November 23 - November 29) Finish the update and improvement of all use cases in the contents introducing people to LORIS.
Project Finalization (November 30 - December 5) a) Clean up all the documentation contributions that I created. b) Merge all created pull requests on GitHub and close all issues that I created. c) Finish my final project report and submit the report to Google.
VII. Future Deliverables
After the Google Season of Docs 2020, I would like to continue my contributions to documentation for LORIS. Specifically, I would like to discuss with LORIS developers about the possibility to continue updating and creating documentation for new releases. Moreover, I would like to take some extra time to review documentation that I have created during my Google Season of Docs project and check if there is more space for improvement. Finally, since I have a relevant engineering background, I am open to contributing to other aspects of the LORIS software in the future, for example, software development.