Tutorial 1 Productivity tools for software development

There are various useful tools for software development project. We are going to cover some of them in this tutorial for you and your team to start the project.

VSCode Live share

Live Share allows VSCode user to collaborate with others in real time. It allows you to share your code with others and see their code in real time. It also allows you to share your terminal and debug session with others. You can also share your screen with others. Live Share is available for Visual Studio Code, Visual Studio, Visual Studio for Mac, and Visual Studio Code Insiders.

Getting started with Live Share

You will need to install Live Share extension in VSCode from the marketplace (link).

After that, your are ready to share!

How to share your code?

You could start a collaboration session by clicking on the Live Share button in the status bar.

To share your code or workspace with others, you could click on the Live Share button in the status bar and click on Share.

How to join a collaboration session?

To join a collaboration session, you could click on the Live Share button in the status bar and click on Join Collaboration Session. Or by the link provided by the host.

Let’s try it out by joining the session below.

https://prod.liveshare.vsengsaas.visualstudio.com/join?F037BCEDDBDBE600EC0F459FB777F79ABF50

Introduction to Markdown

Markdown is a simple markup language for formatting plain text documents which can be converted to HTML. We can use Markdown to format text, add images, create lists, and table along with HTML. Github provides first-class support to Markdown language. You could use Markdown to create a README file and create a wiki page for your Github repository using the in-place editor when you click edit file. Github also support Markdown in commit message, issues and pull requests.

Getting started with VSCode

  1. create a new file in VSCode and save it as a .md file
  2. Happy writing!

Basic syntax

Let’s start with some basic syntax of Markdown. Here are an overview for syntax supported by Markdown.

  • Bold text
  • Italic text
  • Strikethrough text
  • Links
  • Image
  • Inline code
  • Code blocks

  • Blockquotes

    • Unordered lists
    1. Ordered lists

  • Headings

  • — Horizontal rules
  • Tables |Tables|Are|Cool| |—|—|—| |col 3 is | right-aligned | $1600 | |col 2 is | centered | $12 | |zebra stripes | are neat | $1 |

Headings

Similar to HTML, Markdown also supports headings. You could use # to create headings. The number of # you use will determine the heading level. For example, # is for heading 1, ## is for heading 2 and so on.

# Heading 1
## Heading 2
###### Heading 6

Lists

List is a collection of items in a particular order. Markdown supports both ordered and unordered lists. For unordered lists, you could use - or * to create a list item. For ordered lists, you could use 1. to create a list item.

- Item 1
- Item 2
- Item 3
  1. Item 3a
    - Item 3ab
  2. Item 3b

Blockquotes

Blockquotes are used to highlight a quote from someone or something. You could use > to create a blockquote.

> This is a blockquote

Horizontal rules

Horizontal rules are used to separate content in a page. You could use --- to create a horizontal rule.

Page 1
---
Page 2

Tables

Tables are used to present data in a tabular format. You could use | to create a table.

|Tables|Are|Cool|
|---|---|---|
|col 3 is | right-aligned | $1600 |
|col 2 is | centered | $12 |
|zebra stripes | are neat | $1 |

Code blocks

Code blocks are used to present code or text that is meant to be unformatted. You could use ``` to create a code block. You could also specify the language of the code block to enable syntax highlighting.

    ```javascript
    import { useRoute } from 'vue-router';
    export default  {
        setup() {
            const route = useRoute()

            return {
            msg: 'Hello World'
            }
        }
    }
    ```

import { useRoute } from 'vue-router';
export default  {
  setup() {
    const route = useRoute()

    return {
      msg: 'Hello World'
    }
  }
}

Introduction to Draw.io in VSCode

Draw.io or diagrams.net is is a free online diagram software for making flowcharts, process diagrams, org charts, UML, ER and network diagrams. In VSCode marketplace, there is an unofficial extension for integrating it into VSCode, making it becomes more useful. In this part, we will learn how to create drawings in VSCode with draw.io extension.

Create drawings in VSCode with draw.io extension

  1. Install the Draw.io extension in VSCode from the marketplace (link)
  2. Open a new file in VSCode and save it as a .dio file Demo
  3. Add more shapes to side panel by clicking on the + More Shapes... button at bottom of the side panel. There common shapes we needed, for example Bootstrap, Flowchart and etc…
  4. Drag and drop shapes to the drawing area and play around with properties of the shapes on the right side panel such as color, size, font, etc…

Export drawings to other formats

  1. Click on the File button at the top menu bar and select Export....
  2. Input the file name and select the format you want to export to. It supports exporting to png, svg, and drawio formats.
  1. Click on the File button at the top menu bar and select Embed > IFrame.
  2. Copy the URL from src attribute in the <iframe> tag of generated HTML code.

Drawing diagrams for software development with Mermaid.js

Mermaid.js is a simple markdown-like script language for generating charts from text via javascript. The types of charts that it supports are flowchart, sequence diagram, class diagram, state diagram, gantt diagram and git graph diagram. It is a very useful tool for generating diagrams in markdown files for documentation in software development.

To enable Mermaid.js the VSCode’s Markdown preview, please install the Markdown Preview Mermaid Support extension from the marketplace (link).

Otherwise, you could also try it out with their online editor (link).

Types of diagrams supported by Mermaid.js

In our practice, here are some useful type of charts that your would needed during project development.

Flowchart

A flowchart is a diagram that represents an algorithm, workflow or process. Flowcharts are easy to understand diagrams that show how the steps of a process fit together. Flowcharts can also help you see any gaps in your process, or areas where you could make improvements.

You could use the following code to generate a flowchart in markdown. You will need to declare the type of the flowchart as flowchart and specify the direction of the flowchart as TD for top-down, LR for left-right, RL for right-left, BT for bottom-top.

flowchart TD
    Top --> Bottom

Node with same wording will be merged into one node.

flowchart LR
    Left --> Middle
    Middle --> Right

For more flowchart usage, please take a look to the official documentation.

Sequence Diagram

Sequence diagrams are used to show interactions between objects in a system. They are used to show the order of messages exchanged between objects in a system. Sequence diagrams are often used to show the order of events in a system.

An example of user login sequence diagram:

sequenceDiagram
    actor User
    participant System
    User ->> System: Login to system with username and password in login page
    System --) User: Login failed, remain in login page
    System ->> User: Login successful, redirect to homepage

For more Sequence diagram usage, please take a look to the official documentation.

Entity Relationship

Entity Relationship Diagrams (ERD) are used to show the relationships of entity sets stored in a database. An entity set is a collection of similar entities. An entity is an object, a component of data. An entity set can be thought of as a table in a relational database.

Here is an example of ERD for user borrow books:

erDiagram
    User {
        string name
        string email
        string phone
    }
    Book {
        string name
        string author
        string publisher
    }
    Gift {
        string name
        string description
    }
    Join {
        User id
        Gift id
    }
    User ||--o{ Book : borrow
    User }|--|| Join : "Collect gifts"
    Join ||--|{ Gift : "Collected by"

For more ERD usage, please take a look to the official documentation.

Gantt chart

Gantt chart is a type of bar chart that illustrates a project schedule, showing the start and finish dates of the terminal elements and summary elements of a project.

Here is an example of Gantt chart for your project:

gantt
    title Project plan
    dateFormat  YYYY-MM-DD
    section Week 1
        Forming group :a1, 2023-01-09, 7d
    section Week 2
        Project selection :a2, 2023-01-15, 1d
        First development iteration:after a2, 4d 
        Create project files and repo :after a2, 2023-01-17, 1d

For more Gantt chart usage, please take a look to the official documentation.

Mermaid.js in Draw.io

Mermaid.js is also supported in Draw.io for generating diagrams in Draw.io diagrams. You will need to install the Draw.io Integration: Mermaid plugin extension from the marketplace (link).

After installation, there will be a new Mermaid section in the side panel of Draw.io. You could drag and drop the Mermaid shapes to the diagram canvas to generate the corresponding diagram. To edit the diagram, simply double-click on the shape to edit code in Mermaid.js syntax.