Technology Trends/User Guide

From wiki
Jump to navigation Jump to search


Status Translation
Initial release September 1, 2019
Latest version September 1, 2019
Official publication User Guide.pdf
Template Template.html
Traffic cone.png This page is a work in progress. We welcome your feedback. Please use the discussion page for suggestions and comments. When the page is approved and finalized, we will send it for translation.

This User Guide provides the instruction necessary to upload a new technology trend briefing paper. Most of the code is written in HTML using the CSS style. The goal of this page is to provide a step by step guide on how to create a page.

Hide Detailed View


Initialization and Configuration

Getting a GCcollab account

Before starting to code, you will need an account on GCcollab in order to create and edit existing GCwiki source code. If you have an Governmenet of Canada email account the process should be simple. If not, a public servant with an existing account can invite you using the invite button located at the top of the dashboard.

Installing a Code Editor

Most of the code written on the technology trend page is done in HTML and CSS since they were found to be the easiest and offer versatily when it comes to styling. Therefore, it is highly recommended that you use a Code Editor for the publishing process. They are not obligatory for the purpose of publishing technology trend. However, they simplify and accelerate the process. Below are three of the most popular environment and should be sufficient for the process. These platforms offer important tools and features such as syntax highlighting, file explorers, console, etc. Since Visual Studio Code is currently the most popular choice, examples in this user guide will use this editor, however the process is similar with others.

  • Visual Studio Code : A completed editor where all the tools are available after installation.
  • Atom : A simple and lightweight editor where most features are avaiable as packages and can be installed throught the settings.
  • Sublime Text : A classic editor offering the barebones functionnality.

Initializing the Code Editor

After installing the editor, follow these following steps to start creating your first file. For this example, we will be using Visual Studio Code but the process is similar on other platforms.

  • Creating a Workspace folder : A workspace is a project folder located on your local computer that contains all of the project code. Locate a suitable directory on your computer a create an empty folder with an appropriate name (such as "GCwiki").
  • Adding the folder to the Editor's workspace : On Visual Studio, open the file explorer located on the left or by pressing Ctrl+Shift+E. Right click on the Workspace portion and click "Add Folder to Workspace". Locate and select the previously created folder as your new workspace.
  • Creating a new file : Right click on the project folder "GCwiki" and select new file. Enter an appropriate filename with an ending of ".html" such as "EN - Example.html". Use this newly created file to write all the code for the technology brief.
  • Adding the template's code : Navigate to the template page. On the upper navigation bar, select "view source" or, if you are logged in, "edit source". From there, copy and paste the template's code to your file. This template offers all the technology brief empty code.
  • Adjusting the template's code : Before starting to publish the technology brief content, you need to adjust the template's information. All comments in the brackets "<!-- comment -->" need to be replace by the corresponding information. Don't forget to use the underscore (_) when using links and files

Publishing on GCwiki

During the technology trend publishing process, it is important to view how to code is being

  • Creating a new page : To create a new page on GCwiki, you simply have to enter the corresponding name in the URL bar on top of your browser. For example : the link for the this user guide is "https://wiki.gccollab.ca/Technology_Trends/User_Guide". The platform will offer you the option the create the corresponding page. Warning! Once a page has been created, it cannot be deleted so enter a valid name that follows the standards. For english page, name's starts with "Technology_Trends/" followed by the technology name using underscores rather than space. For french page, use "Tendances_Technologiques/" followed by the same structure.
  • Adding the code : Navigate to the "Edit Source" tab on top of the page to publish your code. Copy and paste the corresponding code from Visual Studio Code to GCwiki. Pres "Save changes" to publish or "Show preview" to view the resulting code.

Visual Studio Code : Settings and Shortcuts

After installing Visual Studio Code, there are some parameters you might want to change and shortcuts you might want to know.

  • Auto-completion : VS code has an autocomplete feature by default where if you start writing the tag and then press "tab", it will create the starting and closing tag. Ex: div.orange -> <div class="orange"></div>
  • Zoom : To change the zoom level of the interface, press Ctrl+Shift+P to open the command bar and search for "Preferences: open settings (JSON)". In that file, change and save the "window.zoomLevel" to a suitable value.
  • autoClosingTags : By default, VS code will recognise and try to close tags. However, this feature may not be suitable. To disable it, go to the same settings.json file as before and set the value to "false".

Basics of HTML and CSS

This section introduces the fundamentals of HTML and CSS.

HTML is markup language meaning that it only describes the structure of a Web page and how the browser should display the content. HTML elements are represented by tags which usually consists of a start tag and an end tag with the content inserted in between. These tags affects the content is specific ways. Here are some basic examples :

Markup Renders as
<h1>Header 1</h1> Header 1
<h2>Header 2</h2> Header 2
<p>Paragraph</p>

Paragraph

<div>Division</div>
Division
<b>Bold</b> Bold
<i>Italic</i> Italic
<u>Underline</u> Underline

HTML tags can have attributes that provide additional information about that element. They are always specified in the start tag. These attributes can change the behavior of the HTML element such as the style attribute used to specify the styling of an element. The more common attributes are the id used to define unique element and the class used to define a elements sharing the same property. Once an HTML element has a class or an id, its style or behavior can be changed using CSS by adressing the corresponding name. Here are some examples :

Markup Style Renders as
<span style="color:red;">Red text</span> red
<span id="blueText">Blue Text</span> #blueText { color: blue; } Blue Text
<span class="green">Green Text</span> .green { color: green; } Green Text

Most of the publishing work is done in HTML using classes to modify the style and the behavior of specific content. Editing the CSS shouldn't be necessary

Technology Trend Content Publishing

After the Code Editor has been installed and the template has been copy-pasted into the new technology brief file, you are ready to start publishing. Each brief is different so use the information provided below accordingly.

Information

The first step is to change the template's information accordingly. Most of these changes affects the right-sided table containing the brief's information. These modifications are commented such as <!-- comment --> to make it easier to locate and make the require changes. Be careful! The information follows a standard syntax and format that must be respected for the sake of consistency. Only the part in green needs to be changed. There is no need to understand what it does

line # Name Description Example
2 French Version Link This GCwiki link redirects to the french version of this page. [[fr:Tendances_Technologiques/Guide_d'Utilisateur]]
13 Brief Title This is the name of the brief in the side table in plain text. User Guide
20 French Version Link This link redirects to the french version. [[Tendances_Technologiques/Guide_d'Utilisateur|Guide d'Utilisateur]]
25 Logo File Link This link displays the logo. [[File:Technology_Trends_-_User_Guide.png|200px]]
28 Status Chose one of these 4 states this brief is currently at. Unassigned / Development / Translation / Published
32 Initial Release Simple date text September 1, 2020
36 Latest Version Simple date text September 1, 2020
40 Publication File Link This link shows the published version of this brief. [[Media:EN_-_Technology_Trends_-_User_Guide.pdf|User Guide.pdf-->]]
78 Wiki Page Name This changes the name of this GCwiki page. #firstHeading::after{ content:"User Guide"; }

Headers

Headers indicate a section of the document. In the brief, headers starts at H2 and go up for sub-sections. Any headers will show up in the table of content located at the top of the page.

Markup Renders as
<h2>Business Brief</h2> Business Brief

Paragraph

A paragraph tag, denoted by the letter “p”, is opened like all other HTML tags with an opening “<p>” tag and a closing “</p>”. In the brief, when an entire paragraph (as shown below) needs to be uploaded with no special rendering this can be done using the paragraph tag.

Markup Renders as
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed quis gravida tellus. Pellentesque egestas nisi id diam accumsan, non vulputate neque viverra. Aenean ut tempus turpis. Nullam ac pellentesque ligula.</p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed quis gravida tellus. Pellentesque egestas nisi id diam accumsan, non vulputate neque viverra. Aenean ut tempus turpis. Nullam ac pellentesque ligula.

In the brief, when an entire paragraph needs to be hidden/collapsible this can be done by making the paragraph tag part of the class “highlighted mw-collapsible-content”. The CSS will render it as seen below.

Markup Renders as
<p class="highlighted mw-collapsible-content">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed quis gravida tellus. Pellentesque egestas nisi id diam accumsan, non vulputate neque viverra. Aenean ut tempus turpis. Nullam ac pellentesque ligula.</p>
Hide Detailed View


Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed quis gravida tellus. Pellentesque egestas nisi id diam accumsan, non vulputate neque viverra. Aenean ut tempus turpis. Nullam ac pellentesque ligula.

When only part of a paragraph needs to be hidden/collapsible the paragraph will need to be separated into several paragraph tags based on if they need to be hidden/collapsible or not. Parts that do not need to be hidden/collapsible will be part of the class “inline”. This allows the CSS to render the entire paragraph as one piece of text. Areas of text requiring still to be hidden/collapsible are made part of the class “highlighted inline mw-collapsible-content”. An example can be seen below.

Markup Renders as
<p class="inline">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p><p class="highlighted inline mw-collapsible-content">Sed quis gravida tellus. Pellentesque egestas nisi id diam accumsan, non vulputate neque viverra.</p><p class="inline"> Aenean ut tempus turpis. Nullam ac pellentesque ligula.</p>
Hide Detailed View


Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Sed quis gravida tellus. Pellentesque egestas nisi id diam accumsan, non vulputate neque viverra.

Aenean ut tempus turpis. Nullam ac pellentesque ligula.

Multiple collapsable paragraph

Markup Renders as
<p class="inline">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p><p class="highlighted inline mw-collapsible-content">Sed quis gravida tellus. Pellentesque egestas nisi id diam accumsan, non vulputate neque viverra.</p><p class="inline-spacer"></p><p class="inline">Nunc vel sapien efficitur, convallis nulla bibendum, gravida metus.</p><p class="highlighted inline mw-collapsible-content">Integer pharetra aliquet nibh non interdum.</p>
Hide Detailed View


Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Sed quis gravida tellus. Pellentesque egestas nisi id diam accumsan, non vulputate neque viverra.

Nunc vel sapien efficitur, convallis nulla bibendum, gravida metus.

Integer pharetra aliquet nibh non interdum.

List

Lists can be created in two ways. These are unordered lists which are simply bulleted, and ordered lists which are numbered. Unordered lists like all HTML tags are denoted by an opening “<ul>” tag and a closing “</ul>” tag. In the same manner, ordered lists are opened with an opening “<ol>” tag and a closing “</ol>” tag. The items in the list will be placed within these tags. List items require being individually wrapped in a “<li>” opening tag and closing “</li>” tag. An example of this can be seen below.

  • ul : unordered list
  • ol : ordered list
  • li : list item

Markup Renders as
<ul>
 <li>Element 1</li>
 <li>Element 2</li>
</ul>
  • Element 1
  • Element 2
<ol>
 <li>Element 1</li>
 <li>Element 2</li>
</ol>
  1. Element 1
  2. Element 2

If elements in the list require being hidden/collapsible the entire list will need to be made as a list of lists. When doing this collapsible items will be placed in a list that is part of the class “highlighted mw-collapsible-content”. An example of this can be seen below.

Markup Renders as
<ul>
 <li>Element 1</li>
</ul>
<ul class="highlighted mw-collapsible-content">
 <li>Element 2</li>
</ul>
Hide Detailed View


  • Element 1
  • Element 2
<ol>
 <li>Element 1</li>
</ol>
<ol class="highlighted mw-collapsible-content" start="2">
 <li>Element 2</li>
</ol>
Hide Detailed View


  1. Element 1
  1. Element 2

Tables

• table : (tag) Table
• tr : (tag) Table Row
• th : (tag) Table Header
• td : (tag) Table Detail
• wikitable : (class) Adds the Wikipedia table style to a table.
• sortable : (class) Adds sortable functionnality to a table.
Markup Renders as
<table class="wikitable sortable">
 <tr>
  <th>Header 1</th>
  <th>Header 2</th>
 </tr>
 <tr>
  <td>Detail 1</td>
  <td>Detail 2</td>
 </tr>
 <tr>
  <td>Detail 3</td>
  <td>Detail 4</td>
 </tr>
</table>
Header 1 Header 2
Detail 1 Detail 2
Detail 3 Detail 4

Links, Images and Files

Links, files, and images are all denoted in a similar fashion with the double square brackets and a vertical line separator as such “[[ | ]]”. For links the left side of the separator contains the URL of the link (if it is a wiki link the title of the page can be given). On right side of the separator is the name the user wishes to be displayed. Similar to links, files contain the file name to be displayed on the right side of the separator. The left side contains file name that was uploaded to the database separated by underscores. The left side also contains the prefix “Media:EN_-_”. An image is denoted the same way. Except the right side of the separator contains the size of the image in pixels (eg. 40px). The left side contains the name of the image with the prefix “File:”. Examples of all three can be seen below.

Images and files need to be uploaded to the database by clicking the “Upload file” link on the left side of the page.

Markup Renders as
[https://www.canada.ca/en.html Canada.ca] Canada.ca
[[Technology_Trends|Home Page]] Home Page
[[Media:EN_-_Technology_Trends_-_User_Guide.pdf|User Guide pdf]] User Guide pdf
[[File:Traffic_cone.png|40px]] Traffic cone.png

References

References like other HTML tags are created with an opening <ref> tag and a closing </ref> tag. Within the reference tags the APA citation can be placed. After the citation a link can also be place with the same format as previously discussed or simply with one square bracket pair like “[ ]”. Doing so, will cause the citation in the text to appear as a number, as seen in the example below.

Markup Notation
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.<ref>Wikipedia. (2019, September 1). [https://en.wikipedia.org/wiki/Main_Page Wikipedia]. Retrieved from Wikipedia</ref></p>

Lorem ipsum dolor sit amet, consectetur adipiscing elit.[1]

References

  1. Wikipedia. (2019, September 1). Wikipedia. Retrieved from Wikipedia

Main Pages

Recent additions and bottom table

Markup Renders as
<table>
 <tr>
  <td>[[File:Traffic_cone.png|40px]]</td>
  <td class="disclaimerText">Recent additions include [[Technology_Trends/Blockchain|Blockchain]], [[Technology_Trends/Drones|Drones]].</td>
 </tr>
</table>
Traffic cone.png Recent additions include Blockchain, Drones.
<table class="wikitable sortable technology-table" style="border: 0px solid;">
 <tr>
  <th colspan="3">Name</th>
  <th>Status</th>
  <th style="white-space: nowrap;">Release Date</th>
  <th>Official Publications</th>
 </tr>
 <tr>
  <td style="border-right: 0px solid; text-align:right;">Blockchain</td>
  <td style="border-left: 0px solid; border-right: 0px solid;">-</td>
  <td style="border-left: 0px solid; text-align:left">Chaîne de Blocs</td>
  <td>Published</td>
  <td>2019-05-23</td>
  <td>EN - FR</td>
 </tr>
 <tr>
  <td style="border-right: 0px solid; text-align:right;">3D XPoint (Optane)</td>
  <td style="border-left: 0px solid; border-right: 0px solid;">-</td>
  <td style="border-left: 0px solid; text-align:left">3D XPoint (Optane)</td>
  <td>Development</td>
  <td>FY 19-20 Q2</td>
  <td></td>
 </tr>
</table>
Name Status Release Date Official Publications
[[Technology_Trends/Blockchain|Blockchain]] - [[Tendances_Technologiques/Chaîne_de_Blocs|Chaîne de Blocs]] Published 2019-05-23 [[Media:EN_-_Technology_Trends_-_Blockchain.pdf|EN]] - [[Media:FR_-_Tendances_Technologiques_-_Blockchain.pdf|FR]]
3D XPoint (Optane) - 3D XPoint (Optane) Development FY 19-20 Q2

Hype cycle table

Hype cycle table, example using blockchain

Markup Notation
<div class="container">
 <div class="row">
  <div class="col-sm-8">[[File:EN_Technology_Trends_-_Blockchain_Hype_Cycle_2018.png|center]]</div>
  <div class="col-sm-4">
   <table class="wikitable hypecycleTable">
    <tr>
     <th>English</th>
     <th>Français</th>
    </tr>
    <tr>
     <td>Figure 1. Hype Cycle for Blockchain Technologies, 2018</td>
     <td>Figure 1. Rapport Hype Cycle sur les technologies de la chaîne de blocs, 2018</td>
    </tr>
    <tr>
     <td>Expectations</td>
     <td>Attentes</td>
    </tr>
    <tr>
     <td>Time</td>
     <td>Temps</td>
    </tr>
   </table>
  </div>
 </div>
</div>
• div : (tag) Division
• container : (class) Creates a container for a group of elements.
• row : (class) Creates an inline space inside the container.
• col-sm-8 : (class) Creates a column of width 8/12.
• col-sm-4 : (class) Creates a column of width 4/12.
Renders as
EN Technology Trends - Blockchain Hype Cycle 2018.png
English Français
Figure 1. Hype Cycle for Blockchain Technologies, 2018 Figure 1. Rapport Hype Cycle sur les technologies de la chaîne de blocs, 2018
Expectations Attentes
Time Temps