This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- National Resource for Network Biology (NRNB)
- Technical writer:
- Prubhtej_9
- Project name:
- Create user documentation for SynBioHub & develop tutorials for specific use cases
- Project length:
- Standard length (3 months)
Project description
Abstract
A User documentation is designed to assist end users to use a product or service. Good user documentation is very important because it provides an avenue for users to learn how to use a software, its features, tips, tricks and also resolve common problems encountered when using the software. It also reduces support cost and is part of the corporate identity of the product, i.e. a good user documentation is a sign of a healthy product and the developer team. Without a good user documentation, a user may not know how to do the things that are mentioned above effectively and efficiently. User documentations can play a pivotal role in ensuring a product's success because great communication is and will always be at the heart of any business or product and a great documentation just takes that communication and puts it in a manageable framework that everyone can access for success. 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 where it can then be integrated into CAD tools for building genetic designs. SynBioHub contains an interface for users to upload new biological data to the database, to visualize DNA parts, to perform queries to access desired parts, and to download SBOL, GenBank, FASTA, etc. Various research papers and some tutorials are also available on the internet, such as follows: 1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 SynBioHub has some documentation to speak of which is only related to the API whereas no documentation is there for the GUI.
Current State of the documentation:
Currently, the user documentation is available at :“https://synbiohub.github.io/api-docs/#about-synbiohub “. This is just the API documentation and the GUI documentation doesn’t exist which can help the user navigate within the design repository. Also the API documentation needs a bit of updation as well, with some specific topics such as troubleshooting of certain peculiar issues that a user may face. While the organisation has recorded some tutorial videos, such as the one here. There is really no written user documentation about SynBioHub which can guide the user.
Why is your proposed user documentation an improvement over the current one? I’ll be building the GUI documentation from scratch using github and markdown as suggested by the mentor, Mr. Chris Myers. The proposed user documentation will be structured to improve and ensure efficiency, consistency, and peace of mind for any end user. It will contain written guides and its associated images, include instructions and explanation on how to use each feature of the open source simulator SynBioHub. During the discussions with the Mr. Myers , it was also decided that the API documentation will be merged with the GUI and will contain 6 sections namely out of which 6th section is going to be optional. The sections are mentioned as follows: 1. Introduction 2. Installation instructions a) From prebuilt image b) From source c) NGINX configuration 3. User Instructions a) Detailed instructions on how to use each GUI feature b) Tutorials for common use cases 4. API Documentation - Endpoints section 5. Plugin Documentation 6. Troubleshooting and future references.
Part-1:
In this section, the users will be provided with a detailed introduction and various tutorials with respect to SynBioHub.
Part-2:
In this section, the various ways through which the user can install the open source software using various methods, namely: a) From prebuilt image b) From source c) NGINX configuration
Part-3:
This is the most crucial part of the documentation and will take up most of the time. Herein, each and every minute detail will be added in context to the GUI. As mentioned above mainly two concerns will be addressed in this section i.e. detailed instructions on how to use each GUI feature and some tutorials for common use cases.
Part-4:
As mentioned above, slate will be used to generate the documentation of this part. In this section the following endpoints will be included: 1. User Endpoints 2. Search Endpoints 3. Download Endpoints 4. Download Endpoints 5. Submission Endpoints 6. Permission Endpoints. 7. Edit Endpoints 8. Attachment Endpoints 9. Administration Endpoints
Part-5:
In this section, the plugin documentation will be included which is already present in the old SynBioHub documentation. This section will be sub-divided into two sections, namely: plugin specification and implementation. Part-6: [Optional] This section will include, a very common list of errors that users face and will also consist of some troubleshooting instructions. As per the discussion with the Mr Myers, it has been decided that this section can be merged with the introduction section, if that doesn’t get too long. Analysis Mr. Myers and I had a conversation regarding how to update the existing documentation and also to write a new one for the GUI . In those few conversations we formulated a basic layout for the new documentation which has been mentioned above and an estimate timeline has been given on page 5 below. As per the discussion, I’ll be using github and markdown for building the documentation for every section except Part-4 of the documentation wherein slate will be used. Slate:- Slate helps you create beautiful, intelligent, responsive API documentation. Slate is a Ruby-based tool that generates a great-looking, three-panelled API documentation static site from a set of markdown files. It was built by developer Robert Lord in 2013 when he was an 18-year-old intern at travel software company ‘Tripit’. He convinced his boss at the time to let him open-source the project and the rest is history. It has the following features: • Clean, intuitive design — With Slate, the description of your API is on the left side of your documentation, and all the code examples are on the right side. Inspired by Stripe's and PayPal's API docs. Slate is responsive, so it looks great on tablets, phones, and even in print. • Everything on a single page — Gone are the days when your users had to search through a million pages to find what they wanted. Slate puts the entire documentation on a single page. We haven't sacrificed linkability, though. As you scroll, your browser's hash will update to the nearest header, so linking to a particular point in the documentation is still natural and easy. • Slate is just Markdown — When you write docs with Slate, you're just writing Markdown, which makes it simple to edit and understand. Everything is written in Markdown — even the code samples are just Markdown code blocks. • Write code samples in multiple languages — If your API has bindings in multiple programming languages, you can easily put in tabs to switch between them. In your document, you'll distinguish different languages by specifying the language name at the top of each code block, just like with GitHub Flavored Markdown. • Out-of-the-box syntax highlighting for over 100 languages, no configuration required. • Automatic, smoothly scrolling table of contents on the far left of the page. As you scroll, it displays your current position in the document. It's fast, too. We're using Slate at TripIt to build documentation for our new API, where our table of contents has over 180 entries. We've made sure that the performance remains excellent, even for larger documents. • Let your users update your documentation for you — By default, your Slate-generated documentation is hosted in a public GitHub repository. Not only does this mean you get free hosting for your docs with GitHub Pages, but it also makes it simple for other developers to make pull requests to your docs if they find typos or other problems. Of course, if you don't want to use GitHub, you're also welcome to host your docs elsewhere. • RTL Support Full right-to-left layout for RTL languages such as Arabic, Persian (Farsi), Hebrew etc. Verdict Slate is one of the most powerful open source software for generating the documentation and as per the discussions with my mentor, Mr. Chris Myers I’ll be using slate for Part-4 and for other parts, github and markdown will be used. A more detailed view of the documentation is discussed in the sections below. Structure for the proposed documentation I created a structure for the SynBioHub User Guide which can be found on page 2. This structure is accepted and has already been modified by Mr. Myers . Project Goals 1. Restructure the documentation. 2. Update the documentation to fit the modern versions of SynBioHub. 3. Remove obsolete information. 4. Rewrite the user documentation to make it easier to understand. 5. Include a brief pre-requisite’s section to the documentation for new contributors so as to increase their basic understanding of basic biological concepts and the interface of SynBioHub.