Season Of Docs Project Report: Create user documentation for SynBioHub & develop tutorials for specific use cases (NRNB)

Abstract

SynBioHub is a design repository for synthetic biology. It is available both as a public website and as open source software. SynBioHub uses the Synthetic Biology Open Language(SBOL), an open-source standard for representing genetic designs, and also allows sharing design parts from GenBank and FASTA files.
SynBioHub can be used to publish a library of synthetic parts and designs as a service, to share designs with collaborators, and to store designs of biological systems locally. Data in SynBioHub can be accessed via the HTTP API, Java API, or Python API.

During the Google Season of Docs program, I worked with National Resource Network Biology organization on the project titled, Create user documentation for SynBioHub & develop tutorials for specific use cases. The original project proposal can be found here.

Project Goals

After my proposal was accepted by NRNB organization, my mentors and I agreed on the goals that I was expected to achieve during the Google Season of Docs program. The aforementioned goals can be found below:

1. Restructure the documentation.
2. Update the documentation to fit the modern versions of SynBioHub.
3. Remove obsolete information.
4. Write the user documentation to make it easier for the users to understand.
5. Use Hugo static site generator and Github pages to publish the documentation online.
6. Writing a few sections from scratch in the documentation including user documentation, setup, plugins, etc.

Community Bonding: Taking the Project Forward

• My mentors and I mutually agreed on the time that we were to meet every week as well as the channel of communication. It was decided that we'll be meeting every Wednesday at 11:30 PM(IST) which was later shifted to 12:30 AM(IST) for the last couple of weeks or so, due to the USA shifting to the winter time. For communication, we put in use the Email. I was instructed by my mentor, for publishing a weekly blog that contained:
  • Tasks assigned for that particular week.
  • Tasks I was able to accomplish.
  • The doubts I encountered during that week.

I've published around a total of 15 blogs during the course of this project.

• Refined my goals and set certain expectations with my mentor and also learned more about the SynBioHub community as well as about SynBioHub. I also ensured that the proposal that I'd drafted was in line with what the organization expected.

• Tried to use Hugo as well as Github pages, to a certain extent, since this was the first time, that I was using both these tools.

• Established and started to insert the documentation into 2 repositories, which are as follows:

  1. This repository contains just the source code for the documentation i.e, both the markdown that I wrote as well as the compiled or the fully rendered code of the documentation in the folder titled, Public.
  2. This repository contains the fully rendered code for the website.

• Removed the Non-API documentation from the API documentation of SynBioHub.

• Started to insert content into the newly developed documentation of SynBioHub.I migrated a few parts of the documentation from the already existing API documentation to the newly developed documentation of SynBioHub.

• Read this research paper sent by my mentor, which helped me to increase my knowledge of what SynBioHub really does.

Documentation Development Phase

• During this phase, we had another brief discussion about the structure of the documentation and it was decided that there's a need to have a Setup section, which'll describe how to setup a local instance of SynBioHub.

• Re-wrote the installation section, though I used some instructions from the API documentation as well.

• Also, included the plugins section to the documentation. All credits for this section go to Jeanet Mante, who'd written a doc on plugins. I'd inserted this very doc into the documentation. Though I had to make a few changes, pertaining to the formatting as well as the grammatical aspects of this section.

• Wrote the User Documentation section, which was the main aim of this project. The user documentation had to be modified a few times, so as to satisfy the requirements of the organization, though finally it was accepted. The concept of child pages has also been put to use in this section, wherein the user documentation has been divided into various sub-sections, for the convenience of the user. Each and every term has been explained in details as well as hyperlinks have been provided for further reference.

• Another section titled, Questions and Issues has also been added, which consists of various mailing lists and issue trackers for SynBioHub as well as for this documentation. Using these, you'll be able to get in touch with the developers of SynBioHub, or the maintainers to provide any feedback or report any issue pertaining to SynBioHub.

• Hence, the final layout of the documentation is as follows:

  • About SynBioHub
  • Installation
  • Setup
  • User Documentation
    1. Searching for Information
    2. Viewing and Downloading the Information
    3. Registering and Updating an Account
    4. Submitting, Managing and Updating Submissions
    5. Editing a Submission
    6. Add to an existing collection
    7. Data Sharing Mechanism
    8. Administration
  • API Documentation
  • Plugins
  • Questions and Issues
    1. Mailing Lists
    2. Report an Issue
  • Glossary
  • References

Work Done

• Commits: All the commits I made for the documentation can be found on synbiohub-docs as well as synbiohub.github.io repositories, while the latest SynBioHub documentation can be found here.

• Issues Raised And Resolved: All the issues raised by my mentors can be found here while the issues I was able to successfully resolve can be found here.

Tasks	Planned	Completed
Restructure the Documentation	Yes	Yes
User Documentation	Yes	Yes
Setup Section	No	Yes
Plugins	Yes	Yes
Glossary	No	In Progress
Questions and Issues	No	Yes
References	Yes	Yes
Plugins	Yes	Yes
Installation	Yes	Yes

---

The documentation can be found here.

Challenges during the project

• SynBioHub can run on all of the majorly known operating systems including Linux(Ubuntu), MacOS and Windows and this meant I had to write a user documentation that would be useful for all the types of operating systems, namely Windows, Linux(Ubuntu) and MacOS.

• I did not have much knowledge of SynBioHub, during the initial few days of this project, but by the constant support of my mentors, I was able to learn a lot about the functioning of SynBioHub. During weekly meetings as well as through Emails, they cleared all of my doubts, though some were really basic.

• I was totally unaware of Hugo and Github pages in the early stages of this project. Due to my mentors support, I was able to learn quite a bit about Hugo as well as Github pages. I would also like to thank the maintainer of ACE-documentation's repo, @julianflapper for patiently resolving all my doubts in this regards.

My Learning and Experience

I learned a lot more about the NRNB organization and SynBioHub during the Google Season of Docs program. I was able to learn a lot about general terminologies in genetic biology as well as about the functionalities of SynBioHub. My technical writing skill has definitely become better in the course of this project as well as my soft skills.

Overall, it was one of the best things that happened to me this year. The fact that I was able to contribute to the development of SynBioHub is an honour.

The Way Forward...

A few issues are still left to be addressed as far as the documentation is concerned and I hope to address them positively by the 10th of December'20. Since, I also have a decent programming aptitude, therefore I'll try to contribute to the code base of SynBioHub. I'll judiciously try and improve the documentation as well as the code, as per the requirements of the organization.

Conclusion

I would like to thank my mentor, Prof. Chris J. Myers, Jeanet Mante, Dr. James Alastair McLaughlin and James Scholz for their valuable guidance. I'll always be indebted to them for their help and support, which helped me to complete this project.

In future, I shall always like to be associated with this community and shall like to contribute for the betterment of SynBioHub. It'll always be an honour for me that I was able to contribute to SynBioHub, since it is my first professional engagement in an open source community.