Managing your documents

Documentation plays a crucial role in assisting users with Bioinfopipe and its tools. It serves the purpose of helping users get started quickly, providing timely help during usage, increasing utilization efficiency, and preventing confusion, particularly when configuring tool parameters for an analysis job.

Bioinfopipe incorporates its own documentation system, which offers the following functionalities:

Browsing and Reading Articles: Users can access a range of articles within the documentation system to explore various topics related to Bioinfopipe and its tools. These articles provide detailed information, instructions, and explanations to guide users effectively.

Creating and Managing Articles: Users have the ability to create and manage their own articles within the documentation system. This feature enables users to contribute to the knowledge base by sharing their insights, experiences, and best practices. They can document specific workflows, troubleshooting steps, or any other information they find valuable.

By having an accessible and comprehensive documentation system, Bioinfopipe aims to maximize their productivity and ensure a smooth experience throughout their analysis tasks.

To hold relevant articles, Bioinfopipe sets up 3 basic catalogs as follows:

User manual : User manual maintained by Bioinfopipe.

Tools : Contains tool articles for tools, which can be automatically created for users after created tool.

Guides : Contains guide articles of analysis workflows, which are also shown in tab 'Guides' in left sidebar of analysis session for quick applying analysis jobs.

Miscellaneous : Any other articles can be put here.

The documentation system was structured with following components:

Catalog : A container for grouping articles of similar class, e.g. tools with similar functionality.

Article : An article is a document for a specific topic, e.g. each tool doc is an article.

Section : Sections are basic bricks for building the article; a section can hold sub-sections, so as to construct article outline.

Content : A content object is used to link to a section, but contents are separated from sections, so a section can attach/detach a content and a content can be used by multiple sections, which is particular useful when multiple tool articles with different versions sharing most of same contents.

In this article, users will learn how to browse articles, how to create and manage articles.

1. Viewing articles

To access the user manual in Bioinfopipe's documentation system, you can click on the 'Documentation' menu option and select 'User manual.' This will open the user manual viewer. The main body of the viewer displays the entire selected article. On the left pane, you will find a list of articles that you can select to view. The right pane shows the section structure of the article, allowing for quick navigation within the document. Alternatively, you can go to the Menu Bar, click on 'Documentation,' and select 'User manual' from the dropdown menu. This will also open the user manual viewer with the same layout and functionality as described above.

In addition to the user manual, you can also access articles from the basic catalogs such as 'Tools' and 'Miscellaneous.' Simply click on the corresponding links in the documentation menu or use the dropdown links in the Menu Bar -> Documentation. This will open the viewer, and by default, the main body will display all the articles within the selected catalog. The left pane will show a catalog tree with options to view articles under the 'Public' and 'Private' tabs for public and private articles, respectively. Clicking on a catalog will display a list of articles contained in that catalog in the main body.

The page navigation within the article list allows you to browse through multiple pages, with each page displaying 25 article objects. You can use the 'First,' 'Previous,' 'Next,' and 'Last' icon buttons to navigate between pages. Additionally, you can use the search input box labelled 'Search...' to filter the articles by their names, making it easier to find specific articles of interest.

2. Browsing my documents

Go to menu bar -> Documentation -> My documents, it will open a page where you can browse and mange your articles. In the main body all your articles will be list in the table which contains 5 fields:

Catalog path : The catlog path from the root catalog which is the user ID.

Article name : Name of article.

Last updated : The time the tool last updated.

Invisible : Indicating if the article allowed to be shown in article viewer.

#Sections : The number of sections contained in the article.

You will get all properties for a article by clicking the 'View details' icon button, which showing following additional properties:

ID : A pseudo ID assigned under the namespace of user ID.

Authors : The authors who contributed to the article.

Created at : The time when the article created.

Owner : The owner of the article.

Shared : Indicating if the article being shared with others.

By clicking 'View article' icon button, it opens the article in article viewer for user to view the whole article.

The left pane showing the tree structure of catalogs with user ID as root catalog and basic catalogs 'tools', 'guides' and 'miscellaneous' where users can quickly access the articles hold in a catalog by clicking on the catalog link. Also user can quickly go back to a super catalog by clicking the catalog link in the 'Catalog path' above the main button bar.

By default each page showing 25 article objects and you can navigate the pages by clicking the icon buttons of 'First', 'Previous', 'Next' and 'Last'. You can filter the articles by searching the article name in input box 'Search...'.

2.1. Creating a catalog

Articles are organised in catalogs. Users can create new catalogs to group articles of same kind. To create a new catalog, just click 'Create catalog' button, it will pop up a form titled 'Create a new catalog' with following fields:

Parent : Choose a parent catalog, it is current catalog by default.

Name : Specify a name for the catalog.

Order : Specify a order for the catalog, which will determine the display position under its parent; leave it '0' to automatically be added in the end.

Invisible : Check it if you don't want the article to be shown in article viewer.

Click 'Create' button to create a new catalog.

To edit a catalog, go to the catalog by clicking the catalog link, then click 'Edit catalog' button to edit it and don't forget to save it. And you can delete a catalog by clicking 'Delete catalog' button, and making sure to empty all its sub-catalogs and articles before deleting it.

2.2. Creating an article

There are two types of articles: one is for catalog 'tools' which have predefined sections; the other is for catalog 'guides' and 'miscellaneous' which is empty article by default.

To create a tool article for a catalog ('tools' or its descendants), firstly click the catalog, then click 'Create tool article', it will pop up a form titled 'Create a new article for a tool' which has following fields:

Catalog : It is current the catalog by default.

Tool : Search and select a tool for which the article will be created.

Name : Specify the name of article. It is not the article title which will be defined as the title of head section.

Authors : You can put the authors for this article, separately by comma, e.g. "John xx, Peter xx".

Invisible : You can set you article to be invisible if you don't want it to be shown in the article viewer.

Once click 'Create' button, a new tool article will be created and jump to its article page. You will find all the predefined sections have been automatically created for the tool article including following sections:

Introduction : You can put tool introduction here.

Settings : Explain all tool settings including:

Parameters : Give a description about parameters and how to set arguments for different use cases, one sub-section per parameter.
Output : Give a description about output file object such as file format and column explanation, one sub-section per output object.
Parameters in command-line : You can list all rest of parameters which not configured in the tool, and put some descriptions for them.

Computation : Explain how to set CPU size and memory size for different data size and use cases.

Use cases : You can put some real-world use cases to show how to use the tool for different cases, e.g. data type, study type.

You are welcome to add more sections for the tool article such as benchmark test between similar tools.

Note: don't change section names for predefined sections, because they will be used for creating help links in job settings.

To create a miscellaneous article for a catalog ('miscellaneous' or its descendants), firstly click the catalog, then click 'Create article', it will pop up a form titled 'Create a new article for a tool' which has the same fields as the tool article excepting the field 'Tool'. After clicking 'Create' button, an empty article with only head section will be created and jump to the article page for further construction.

3. Building up an article

To construct an article in Bioinfopipe's documentation system, you can follow these two steps:

Add Subsections to Create an Outline: The first step is to add subsections to create an outline for your article. This step is necessary when creating a new article. You can add subsections manually to organize your content effectively.
Add Contents for the Sections: The second step is to add the actual contents for each section of the article. For tool articles, the sections are automatically created, so you only need to add the contents to those sections.

If you have an article that is another version or variation of a ready article, the best approach is to merge the contents of the existing article into the new one. To merge an article, follow these steps:

Click the 'Merge article' button. This will open a form titled 'Merge contents from an article.'
In the form, you can search for and select the article that you want to merge into the current article.
After selecting the desired article, click the 'Merge' button to initiate the merge process.

Internally, Bioinfopipe will attach all the section contents from the selected article to the sections of the current article where the section names match. This ensures that the contents are merged appropriately.

This functionality is particularly useful when creating articles for different versions of a tool. By merging the contents from an existing article, you can reuse relevant sections and avoid duplicating content, saving time and effort in the documentation process.

3.1. Creating a subsection

To create a subsection, if you are on the article page, just click the 'Add child' icon button for a section in table, it will open a modal popup which has following fields:

Parent : Name of selected section.

Name : Specify a name for the subsection. If you leave it empty, Bioinfopipe will create the name as '<Article ID>.<Section ID>' for you. You can make a meaningful name as '<Article ID>.<Abbreviation>', e.g. 'a1014b.alignment'.

Title : Specify a title for the subsection.

Order : Specify a order for the subsection, which will determine the section numbering; leave it '0' to automatically be added in the end.

Invisible : Check it if you don't want the subsection to be shown in article viewer.

After clicking 'Create' button, a new subsection created and shown in table.

Also you can click on a section name to go to the section page, and click 'Add subsection' button to add a subsection for it.

On a article page, you can edit a section by clicking 'Edit section' icon button. You can delete a section by clicking 'Delete' icon button, and its content will also be deleted if the content solely attached to the section, otherwise its content will be detached. If you are on a section page, you can edit a section by clicking 'Edit section' icon button. To delete a section, just click 'Delete section' button.

3.2. Creating a content

By clicking on a section name in an article page, you can open a section page specifically for that selected section. Additionally, the left pane will display the section tree structure of the article, allowing you to quickly access any section by clicking on the desired section. Sections that have contents will be marked in blue, while sections without contents will be marked in grey.

To create a new content for a section, just click 'Create content' button or icon button. This will open a form page titled "Create content - <section name>," where <section name> represents the name of the section you are creating content for. In the general settings section of the form, you will find the following fields:

Name : Specify a content name, it is the section name by default.

Title : Content tile, it is the section title by default; The section will apply section title by default, if unset, then apply its content title.

Authors : Names of authors who contributed to this content, separately by comma, e.g. 'John Doe, Jane Smith'.

Job : This is only for guide article. Users can specify a pre-configured job for a analysis step, which can be directly applied in a analysis session.

Then you can start to write your content using the editor on the page. The editor is a simple WYSIWYG (What You See Is What You Get) editor, and you can access its functionalities from the button bar or through shortcut keys. Click the "Help" button to view the available shortcuts. If desired, you can edit the content in full-screen mode by clicking the "Full Screen" button. You can also directly edit the HTML code of the content by clicking the "Code view" button. To get a stylish table you can edit a table in MS Excel then copy it to MS Word and then copy it into the content editor. Once you have finished writing your content, click the "Create" button to create a new content object attached to the section.

Please note that you can always modify the content after creating it. If you need to edit a content, click the 'Edit content' button or icon. This will open the content form page, allowing you to make changes to the content. To delete a content, click the 'Delete content' button.

If you want to attach a different content to the section, click the 'Attach content' button. This will allow you to search for and select a different content to attach, automatically detaching the current content. To detach the current content without attaching a new one, simply click the 'Detach content' button.

3.3. Sharing an article

If you are a Org user, you can share your articles to any other subscribed users.

To share a article, go to the article page and click the 'Share article' button, it will pop up a form titled 'Share an article' which has following fields:

Share to : The users or teams you would like to share to, you can put user email addresses or team IDs, all separated by ';'.

Share group : Or you can select a predefined sharing group in your account admin, which will override 'Share to' field.

Days for sharing : You can set sharing time span by days, it is 30 days by default.

The users shared with will find the shared articles in their article viewer.

3.4. Copying as new article

You can create a new article by copying a current article to a new article. To do so, just click 'Copy as new' button in a article page, it will pop up a form titled 'Copy article as new' containing following fields:

Catalog : Specify a catalog for the new article.

Name : Specify a new for new article.

Authors : The author list of new article.

Invisible : Check it if you don't want it to be shown in the article viewer.

After clicking 'Copy as new' button, a new article will be created which have the same structure of sections and attach the same contents.

4. Handling your contents

In Bioinfopipe's documentation system, the section content objects are independent from section objects. Like section objects, content objects are also contained in catalogs. When you create a new content in a section page, the content object will be hold in the same catalog as the section.

By clicking 'Manage contents' button in article browser page, you can open content browser page titled 'Browse and manage section contents', where you can directly manage all contents. It will show up all content objects by default in table which have 4 fields:

Catalog path : The catlog path from the root catalog which is the user ID.

Content name : Name of content object.

Last updated : The time the tool last updated.

#Sections : The number of sections attached to the content.

The left pane showing the tree structure of catalogs where users can quickly access the contents hold in a catalog by clicking on the catalog link. Also user can quickly go back to a super catalog by clicking the catalog link in the 'Catalog path' above the main button bar.

By default each page showing 25 content objects and you can navigate the pages by clicking the icon buttons of 'First', 'Previous', 'Next' and 'Last'. You can filter the contents by searching the content name in input box 'Search...'.

You can create a content here by clicking 'Create content' button, though it is recommended to create a content in a section page. You can edit a content by clicking related 'Edit content' icon button, it will open content form page for you to edit. To delete a content, just click related 'Delete content' icon button to delete it, making sure no section attached to the content before delete it.

By clicking on a content name, you can open a content page where you can also edit content and delete content.