DEV Community: Prubhtej Singh

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

Prubhtej Singh — Thu, 03 Dec 2020 06:23:23 +0000

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:

Restructure the documentation.
Update the documentation to fit the modern versions of SynBioHub.
Remove obsolete information.
Write the user documentation to make it easier for the users to understand.
Use Hugo static site generator and Github pages to publish the documentation online.
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.

Season Of Docs, Meeting-14

Prubhtej Singh — Wed, 02 Dec 2020 14:48:25 +0000

On 25th of November, I had a meeting with my mentors with regards to Google's Season Of Docs project. The mentors had assigned the following tasks:

Solving the issues, posted here.
Preparing the work product, which is to be submitted in fulfilment of the project.

I was able to resolve more than 50% of the issues. Also, I've written a blog post with regards to the Work product, which needs to be submitted. On the next meeting, which is scheduled on 2nd of December'20, will be the last meeting and the main aim of this meeting is to discuss the work product.

Season of Docs, Meeting-13

Prubhtej Singh — Wed, 25 Nov 2020 15:44:34 +0000

On 18th of November, I had a meeting with my mentors with regards to Google's Season Of Docs project. The mentors had assigned the following tasks:

Making certain corrections to the user documentation, few of which are mentioned as follows:
- Inserting tables, wherever there is a possibility
- Creating a section, for Add to a collection
- Making a general section for Viewing a record, which includes all the general details as well as parameters a record page contains. Subsequently, create sections for every type of record, which'll contain sections specific to that record.
- Editing the SPARQL search section.
- Editing the Downloads section.
- Replacing numbering with the bullets.
Writing the Setup section.
Editing some minor errors in the Installation section.
Adding a section/button for Reporting an error.

I was able to complete the following tasks:

Made certain corrections to the user documentation, few of which are mentioned as follows:
- Inserted tables, wherever there is a possibility
- Created a section, for Add to a collection
- Made a general section for Viewing a record, which includes all the general details as well as parameters a record page contains. Subsequently, created specific sections for Collection as well as module.
- Edited the SPARQL search section.
- Edited the Downloads section.
- Replaced most of the numbering with the bullets.
Wrote the Setup section.
Edited some minor errors in the Installation section.
Added a button for Reporting an error.

This week I was able to accomplish almost all of my tasks, and I hope to complete all the sub-sections of viewing by the end of next week.

Season of Docs, Meeting-12

Prubhtej Singh — Wed, 18 Nov 2020 15:54:40 +0000

On 11th of November, I had a meeting with my mentors with regards to Google's Season Of Docs project. The mentors had assigned the following tasks:-

Making the changes to the user docs, as per the discussions.
Making changes to the Installation page.
Removing the contents of the setup page and re-write the setup page. Also, adding the existing info on the setup page to the relevant sections of the user docs.
Adding the visualisation, download and submit plugins to the plugins sections and removing certain sections from the download table.

I was able to complete the following tasks:

Swapped the Viewing section with the registering section.
Added the Searching on a record sub-section under the search section.
Edited the editing a submission section. Added a few more details, which were missing as well as provided the explanations in a bit more detail.
Removed the content from the setup page and added it to the respective sections under the admin section.
Added the visual, submit and the download plugins to the respective sections, under the plugins section.
Somewhat completed the SBOlExplorer section under the admin section.
Made the minor changes to the installation page as per the requirements.

Following are the issues that I faced this week:

Was unable to install SynBioHub, with SBOLExplorer.
Was unable to get to the setup page.
Still some sections in the admin section of the user docs are empty and I'll try to understand their significance in the next meeting.

Further, I'll try and clear all my doubts, in the next meeting and have a brief discussion over the contents of troubleshooting section.

Season of Docs, Meeting-11

Prubhtej Singh — Wed, 11 Nov 2020 15:44:24 +0000

On 4th of November, I had a meeting with my mentors with regards to Google's Season Of Docs project. The mentors had assigned the following tasks:-

Make the first 6 sections a bit more descriptive. (Considering the User as a beginner)
Put in the basic format of the " Admin "section.
Generalise for all synbiohub instances.
De-capitalize in sentences 5.Downloads-Describe the types of files on can download using tabular form.
Adding a link to the SPARQL docs and improving the SPARQL section of the user docs.
Making a few corrections in the Installation section.

I was able to complete the following tasks:

Made the first 6 sections a bit more descriptive: I literally rewrote almost all of the first 6 sections. Adding the details enabled me to understand the complexities of SynBioHub to a much greater extent.
Added the Admin section.
Generalised the user documentation for local as well as global instances.
Added a link to the SPARQL docs and improving the SPARQL section of the user docs.
Made a few corrections to the Installation section.
Downloads-Described the types of files on can download using tabular form.
De-capitalized the first letters in the sentences.

I'd faced the following problems during this week:

I did not have knowledge regarding some technical terms while writing the viewing a resource section, hence I've left that section empty. I'll try and clarify these queries in the next meeting and fill up the blank spaces before the next week's meeting.
I don't have fundamental knowledge about what are remotes and specifically about ICE remote.

I hope to clarify all my doubts in the upcoming meeting i.e, on 11th November'20.

Season of Docs, Meeting-10

Prubhtej Singh — Wed, 04 Nov 2020 12:58:49 +0000

On 28th October, I had a meeting with Jet Mante & James Scholz with regards to my Google's Season Of Docs Project.
Several points were discussed, and they're mentioned as follows:

We'd discussed about Sections of the user documentation and corresponding API calls and resolved my doubt regarding the API calls corresponding to the Data Sharing Mechanisms.
I also had a few doubts regarding the API calls corresponding to certain UI of SynBioHub. Most of them were resolved, but we were unable to reach a common consensus about 3-4 API calls.
We'd briefly reviewed the first 3 sections of the User Documentation.

The mentors had assigned the following tasks:

Adding the SPARQL search sub-section under the Searching using Keywords section.
Elaborating the Downloading sub-section under the 3rd section.
Plan and complete sections 4, 5 & 6.
Proof Read all the 6 sections.

I was able to accomplish the following tasks:

Added the SPARQL search section under the Searching using Keywords section.
Elaborated the Downloading section under the Viewing & Downloading the Information section.
Was able to successfully plan and complete the sections 4, 5 & 6.
Proof read all the 6 sections.

Following are the problems that I'd faced this week:

I did not have much of a knowledge about SPARQL, so initially it was tough for me to write the user documentation for that, but with the guidance of Jet and Prof. Myers I was able to successfully understand the basics of SPARQL and somewhat correlate it with MySQL.
I got a bit confused regarding what should go under section-6 i.e, Data Sharing Mechanisms. After a brief discussion with Prof. Myers, I was able to successfully resolve my queries.

In the next meeting, I hope to clear all my doubts about the API calls corresponding to the UI of SynBioHub & take feedback regarding sections 4,5 & 6 of the User Documentation.

Season of Docs, Meeting-9

Prubhtej Singh — Wed, 28 Oct 2020 14:39:33 +0000

On 21st of October, I had a meeting with my mentors with regards to Google's Season Of Docs project. The mentors had assigned the following tasks:-

Compile a list of pages on synbiohub.org
Which API command corresponds to which page on SynBioHub.org
Prepare a basic layout for the user documentation.
Plan the content for all the sections of User Documentation.
Correcting some minor formatting errors on the Plugins installation page.

On subsequent discussions over the Email, the consolidated list of sections was finalized, which is as follows:

Registering and updating your account
Searching for information
Viewing and downloading information
Submitting, updating, and managing your collections
Editing your submissions
Data sharing mechanisms
Administration

I was able to accomplish the following tasks:

Compiled the list of pages on synbiohub.org
Which of the API command corresponds to which page on SynBioHub.org
Prepared and finalized a basic layout of the user documentation, under the guidance of Prof. Myers
Which pages of synbiohub.org correspond to which section
Corrected a few minor formatting errors on the plugins page.
Completed the user documentation for the first 3 sections as mentioned above.

I'd faced the following issues this week:

Was unable to find pages of Synbiohub.org corresponding to all of the API calls.

In the next meeting, I hope to take feedback regarding, the first 3 sections of the User documentation and resolve all of my doubts regarding SynBioHub's UI once and for all.

Season of Docs, Meeting-8

Prubhtej Singh — Wed, 21 Oct 2020 10:30:18 +0000

On 14th of October, I had a meeting with my mentors with regards to Google's Season Of Docs project. The mentors had assigned the following tasks:-

Removing redundancy in the installation section.
Change the heading "With Explorer" to "With SBOLExplorer"
Unify all installation instructions under the General Section even for different OS's.
Just give the link to Docker and Point them to install Git on their OS.
Replace the navigation step with this statement "Navigate to the directory where you want to install SynBioHub"
Try not to merge commands with the sentences
Change the Ordering, use no's only.
Take out "With Developmental SynBioHub"
Link to the plugins table.
Remove NGINX Config.
Resolving the issue on the Sub-section bar on the Right Hand side of the Plugins page.

I was able to complete almost all the assigned tasks, without any issues except one i.e, "Resolving the issue on the Sub-section bar on the Right Hand side of the Plugins page".

I have opened up an Issue on ACE-documentation's github page with regards to this problem, since it is an unusual one, but still minor. I haven't received any significant response from their side, and I hope to resolve this issue by the end of this week.

I hope to have a more fruitful discussion, about taking this project forward in the upcoming meeting i.e on the 21st of October.

Season of Docs, Meeting-7

Prubhtej Singh — Wed, 14 Oct 2020 12:36:27 +0000

Due to COMBINE2020, this meeting did not take place. Though, via Email, I took a brief feedback with regards to the plugins page.
I had corrected all the errors on the Plugins page, just a minor addition was left, that was to insert a graphic to the plugins page. I was unable to take care of this issue, due to my exams, but I hope to resolve it after I'm done with my exams.
In the next meeting, I hope to have a discussion, on how to take this project forward & I hope that I'll be able to cover up for the lost time.
Once again a Special Thanks to Prof. Myers, for understanding my situation regarding my exams and allowing me to focus on them.
Looking forward to the meeting on 14th of October!

Season of Docs, Meeting-6

Prubhtej Singh — Wed, 07 Oct 2020 14:49:10 +0000

On 30th of September, I had a meeting with Jet Mante and James Scholz with regards to my Google's Season Of Docs project.
Unfortunately, Prof. Myers was unable to join the meeting to due a conflict in his schedule. I was able to successfully resolve almost all of my doubts in the weekly meeting. Jet suggested a few minor changes in the Plugins page of the documentation, which're as follows:-

It might be nice to add the graphic back to the overview section.
I think the numbering of subsections helps as it is difficult to see any difference between the installation and using synbiohub title font.
I think it makes sense to just link out to the installation section for the heading 'using synbiohub'. The common problems and adding plugins to the admin panel could be added to that section.
For the standalone methods:flask servers:anaconda section you have not made some of the code red (it is just formatted as text) 5. this is also the case under the python windows os section and the javascript node.js section
under the naming convention section you replaced "<" and ">" with '"' for the second line, this is odd as quotations are generally not used to signal placeholders
In the naming convention section there is a lack of enter between the final example and the paragraph that starts "The same name is then used"
I think the way recieves and return are structured should possibly be more standard throughout status, evaluate, and run under visual, submit and download
making clear that for evaluate and run endpoints what is recieved is the body of an http post request is a good idea
I think the general 'indentation' of headings should be changed.

I was able to successfully complete all the above tasks except one, i.e "Adding a graphic back to the overview section".

I'll be having a small conversation with Jet over the Email, so as to understand this point to a better extent.

This week's meeting won't be taking place since, my mentors will be taking part in COMBINE2020.
I was also to take part in COMBINE2020, but since my college announced surprise Mid Semester examinations, hence I was unable to, though I'll try to watch the recordings, if they're available.

I would also like to thank my mentors for understanding the situation regarding my examinations and allocating less work!

Season Of Docs, Meeting-5

Prubhtej Singh — Wed, 30 Sep 2020 15:09:08 +0000

On 23rd of September, I had a weekly meeting with regards to my Google's Season Of Docs project. The mentor's had assigned the following tasks :

Finish reading the Plugins Docs and include Plugins doc into the main docs.
Sending the Google doc containing relevant info from ACS research paper.
Solving the Table of contents issue.
Completing the implementation of API using the UI of SynBioHub.
Completing the setup page.
Include the link of the plugins table rather than the whole table on the plugins page.

I was able to accomplish the following tasks:

Extracted out relevant info from the ACS research paper, though it was too much. Hence, on the advise of Prof. Myers I'm trying to reduce the content to 1 paragraph at max containing info. about Plugins ans Web-Of-Registries.
Solved the table of contents issues, thanks to My mentor and developer of ACE-documentation theme.
Included the link of plugins table in the documentation that has already been implemented, hence removing the whole table from the docs, which was not looking up to the mark.
I'm almost done including the Plugins doc into the Plugins section of the documentation. A little bit of formatting and editing is left to be done.
I was able to execute almost all the API's using the UI of SynBioHub.

Following are the issues that I'd faced this week:

Extracted out too much of information from the ACS research paper, hence on the advice of Prof. Myers, I've substantially reduced the content and plan to reduce it further.
I haven't used Sendgrid before, hence it was kind of a challenge for me to learn about it's nuances, but still I was able to complete the Setup page well on time.
I'm still encountering some challenges on running locally onto Ubuntu. Hence, I tried to run it on a Mac, on which it successfully ran without any glitches. I tried to do a bit of research, according to which I need to install docker again onto my PC.
The doc that Jet had sent contained a lot of information on plugins. I do have some doubts and I'll try to clarify them in the meeting.

I was able to complete almost all the tasks, this week well in time. Hope to discuss the upcoming tasks in the next meeting i.e. on 30th September!

Season Of Docs, Meeting-4

Prubhtej Singh — Wed, 23 Sep 2020 14:13:19 +0000

On 16th of September, I had a meeting with my mentors regarding my Google's Season Of Docs project.
The following tasks were assigned to me:-

Correcting the section order of the menu on the LHS of synbiohub.github.io
Provide correct links to the broken ones in the About SynBioHub and the references section.
Renaming the "Further References" section to the "References" section.
Moving the Plugins from the Installation section to the Plugins section and reconfiguring the table using Go-lang templates and partials provided by Hugo.
Changing the docker-installation to something more appropriate.
Include installation instructions for Mac OS and Linux OS to the installation section.
Remove all the content from the Source installation section and provide a link to the github repository.
Make a separate section for Setup and add some content to it, i.e. about Web-Of-Registries and SendGrid Mail setup.
Go through the doc on plugins sent by Jet.
Try and prepare a doc on Information collected from the assync. research paper that can be included in the documentation.

I was able to accomplish the following tasks:-

Provided correct links to the broken ones in the About SynBioHub section and the References section.
Renamed the "Further References" section to the "References" section.
Changed the docker installation to something more appropriate, though it still requires some improvement.
Included the installation instructions to Mac OS and Linux-Ubuntu 20.04 to the installation section.
Removed all the content from the Source installation section and gave the link to the github repo.
Installed SynBioHub without any error on Ubuntu.
Created a separate section for setup.
Added a brief description about "Web-Of-Registries" to the Setup section.

The Problems that I've encountered this week are:-

Couldn't re-order the menu. I tried to re-order the menu by allocating weight's to every section but surprisingly, it didn't do any good.
Though I was able to move the plugins table from the "Installation" section, but unfortunately I was unable to understand & use the Go-lang template and partials provided by Hugo. I've opened a few PR's on Hugo's repo and I'm hoping to find a feasible solution in the next couple of days.
Wanted to Upload a design to synbiohub.org but was unable to find the link to the repo from which I was to copy the designs.
Was unable to go through the doc sent by Jet fully. Though, I was able to go through the first few pages and had a few doubts.

Hope I'll be able to clarify the doubts that I have and plan tasks for the upcoming week in the next week.