Team:BioIQS-Barcelona/Wiki editing
Outside the Lab | Wiki editing tutorial
Have a look!The iGEM wiki is where teams write all the information about their projects to make it available for teams participating the next year, judges or people interested in the project. It is also the place where team members itself go to remember their iGEM experience and see how the project looks like after all the work done during the summer. The wiki might be the most important derivable of the competition for the iGEM community since it lasts for the subsequent years and it can be inspiring for other iGEM teams. Therefore, having a nice wiki it is a requisite to make an important contribution to the iGEM community. However, most iGEM teams are mainly composed of students of biology-related fields, which usually do not have the necessary skills to set up a wiki.
This tutorial was created with the intention to facilitate learning how to edit a decent iGEM wiki page to team members with no prior experience in wiki editing. This way, teams will be able to document their project in a better way in their wikis and let them focus on iGEM projects without struggling to learn how to edit the wiki. At the end of this tutorial, team members will be able to interact with the iGEM wiki properly and to design their wikis to have an impact in the iGEM community.
This tutorial was created for non-computer science students by non-computer ones. In fact, the idea and the motivation of creating it arose from the difficulties found during the beginning of the summer while editing the wiki. The more we tried to make things work, the more we realized this tutorial could be very useful to other teams.
As the content is created by non-experts, all the concepts are explained so that they can be understood without prior knowledge in web development. This is a must in order to reach the final audience for which the tutorial was created, inexperienced students. However, some concepts might not be exactly accurate in its definition. We did our best to maintain a good equilibrium in being accurate without making things excessively difficult or confusing for inexperienced students. We encourage all expert students to give us their feedback so that we can improve this tutorial and make it even more useful for inexperienced students.
iGEM wikis are becoming more and more good-looking and well designed each year. The most important objective for the wikis is documenting as much as possible iGEM projects instead of impressing the users with its design. In fact, iGEM provides the teams with a standard format in which teams could easily create a simple but fully functional and complete wiki, fulfilling the most important requisite of a wiki. However, creating a well-designed wiki helps to make the information more accessible and clear to the users and improving the navigation through the team’s project. Furthermore, styling the wiki gives a distinctive look to each project which can reinforce the objective of the project. In this tutorial, we are going to show how to use Bootstrap, a popular front-end framework for designing websites. This will facilitate creating a distinctive look easily while making the information readily available to future teams.
This tutorial requires a prior background knowledge in HTML and CSS. Javascript it is not required since the Bootstrap framework provides the wiki with enough responsive elements to make it functional and attractive. This tutorial is not focused on teaching how to code a website, but on giving and teaching how to use some tools that make wiki editing more simple. Therefore, we suggest inexperienced users of this tutorial to look up for learning resources about HTML and CSS on the internet, like the ones found in W3schools or Sololearn. We also recommend learning just the basics of both languages, since during wiki editing it is always possible to look to a HTML and CSS reference to learn how to do specific things. In fact, wiki editing is a very nice opportunity to learn hands-on some front-end development.
The tools explained in this tutorial are very useful to edit the wiki locally and by multiple team members. The tutorial is focused on teaching how to edit the wiki locally (in order to take advantage of the tools that can not be used in the online wiki editing site) always keeping in mind the requirements of the iGEM wiki in the MediaWiki context. Users taking this tutorial will learn how to use a professional code editor like Visual Studio Code and take advantage of their features, how to use a version control system like Git, how to edit the wiki in collaboration with other team members using Github and how to use the Bootstrap framework from its source Sass files to style their wikis. Even more, experienced users will take advantage of learning how to submit files to the iGEM wiki server, how to reference stylesheets or other files in the Mediawiki interface and how iframes can be useful to simulate the useful templates used in the Mediawiki interface. The tutorial consists of 3 videos which sum up to 2 hours of tutorial. We encourage inexperienced students to go through this videos in an ordered way, but it is not a requisite because each video can be understood by itself. Therefore, more experienced users can get the most out of this tutorial jumping directly to their topics of interest to learn more about the iGEM wiki interface. A brief description of the topics covered in each video can be found below. The tutorial consists also of a GitHub repository where the examples used in each video are stored so that the students can reproduce what is done in each video and get hands-on experience. The final version of each example is also provided in order to let more experienced users navigate quickly through the code.
Note that the videos forming this tutorial are stored on the Youtube channel of our team instead of the iGEM server. The examples are also stored in the Github repository of our team. iGEM recommends storing all the information of iGEM projects in the iGEM server or the iGEM Github account because it is the only way to make sure that this information is available through the subsequent years. However, files uploaded to the iGEM server must be less than 100MB of size. This would not allow us to provide videos of the minimum length to teach one concept and with a decent resolution. Doing so is considered a form of cheating in the iGEM competition, but we made sure to be under equal conditions to other teams by uploading all the material of this tutorial before the wiki freeze deadline.
In addition, the wiki and GitHub freeze implies that users can not modify any of the contents after a certain date. By storing all the videos and examples in external servers which we are able to control we are able to incorporate the feedback we receive and improve this material. This way, we will be able to create erratum files or notes providing additional information for each video both in the description in the Youtube video and the Github repository. Therefore, storing the tutorial outside the iGEM server will make possible for us to maintain it.
Note that the audio of the videos is in the Spanish language for the moment due to time limitations. We will upload the English version of the videos as soon as possible to make sure all teams participating in the next year iGEM competition are able to use this tutorial. Meanwhile, only team members with a basic knowledge of Spanish will be able to make use of them. The English version of the videos will be available on our Youtube channel.
We strongly recommend you check out the work that other teams have done regarding wiki editing. The iGEM Marburg 2018 team created a series of indications on how to design an accessible wiki to people with disabilities. You can check them here. The iGEM Virginia 2018 team created a Wiki Build Tool which makes much easier to synchronize the content that we are editing locally with the iGEM server. We encourage all the iGEM team members taking this tutorial to make their wiki accessible following the Marburg team’s indications and use the Wiki Build Tool designed by the Virginia team.
iGEM wiki introduction
The first step in creating an appropriate iGEM wiki is knowing how it should be like. We are going to have a first look to the documentation regarding iGEM wiki and the iGEM wiki interface.
1.1 iGEM wiki documentation: iGEM provides detailed information on what should be the objective of the wiki and some rules that must be followed. Reviewing this documentation will help both inexperienced and experienced users to introduce the wiki and have an idea of what to do.
1.2 iGEM wiki interface: acabar d’omplir
Online editing vs. local editing
iGEM wikis can be edited directly in the MediaWiki interface or uploading the code after editing locally.
Both options have multiple advantages and disadvantages.
This tutorial is based in editing the wiki locally. We strongly recommend to take a look at the Wiki Build Tool developed by the Virginia iGEM team.
This tool has the objective to combine the advantages of editing the wiki online and locally and incredibly simplifies the wiki editing process.
Setting up a code editor (VS Code)
One of the advantages to edit the wiki locally is using a code editor like Visual Studio Code.
This text editor is available for all major OS (Linux, Windows, MacOS) and facilitates code editing.
In this video, we are going to teach how to use it from the very beginning and set up useful extensions.
Live server offers a live preview of the wiki to see changes while editing the wiki. VS Code also features multiple useful functionalities like a colour picker or CSS peek, with which elements of the wiki can be styled easily.
Setting up a version control system (Git, GitHub)
Git is useful to keep track of the progress of wiki editing.
Using this version control system it is possible to go back to certain control points, which is particularly useful to inexperienced users because they will be able to experiment without fear of damaging what is already done.
Connecting this service with an online server like GitHub, multiple team members will be allowed to edit the wiki simultaneously and keep control of all changes.
Implementing this tools is essential to edit the wiki by multiple team members in an ordered and progressive way.
Styling the wiki: Introduction to Bootstrap 4
Bootstrap is a front-end component library which will allow inexperienced users to have an easily customizable and stylish wiki design.
It also incorporates elements to make the wiki responsive, so that it will adapt to mobile devices.
In this first tutorial you are going to learn what is bootstrap, how to create a navigation bar for the iGEM wiki and how to correctly implement Bootstrap in the wiki following the iGEM rules (avoid using CDN).
Styling the wiki with Sass
Sass is an extension of CSS which, among other things, allows the use of variables to define styles.
This can be very useful to modify multiple styles changing just one parameter.
Bootstrap can be compiled from Sass files, so that we can take advantage of Sass to edit the wiki in a faster and smarter way.In this tutorial you are going to learn how to install Sass and use it to change the style of a simple example.
6.1 Installing Sass
6.2 Introduction to Sass & example
Styling the wiki: Customizing
Bootstrap using Sass
Bootstrap can be implemented in diverse ways, but compiling the styles using Sass provides the inexperienced user with multiple advantages that will be explored later on. In this brief tutorial you will learn how to set up Bootstrap to be used in combination with Sass in under 10 minutes.
Styling the wiki:
Hands on example
Finally, in this tutorial you will learn how to make use of the advantages of Sass to customize the navigation bar that was created before using Bootstrap alone.
Using this method you will be able to quickly style the rest of elements of your wiki and design a personalized look for your project.
Simulating wiki templates using IFrame
Mediawiki templates are very useful to introduce elements which are present in multiple pages of our wiki, like the navigation bar and the footer.
In addition, the stylesheets and scripts of the wiki can be added to this templates.
This way, the wiki will load faster after accessing it for a first time, as the stylesheet and scripts of all the pages will already be loaded in the templates.
This behaviour can be simulated locally using IFrame. This will have to be removed when uploading the wiki to the iGEM server. However, their use facilitates the local design of the wiki and makes it more similar to how the wiki will have to look like once uploaded to the iGEM server.
A commented example: complete project description and team member pages
In this tutorial you will see two example pages that could be perfectly valid for the iGEM wiki.
The first one is the project description team and serves as a good example to see how editing Bootstrap from Sass is an easy way to have a simple, elegant and personalized wiki design.
The second one is the team members page, which demonstrates how Bootstrap can also be used to create elaborated and responsive wiki pages in a smart way. This examples also serve as a clarification of all the concepts explained so far as they both make use of IFrame to represent the Mediawiki templates.
Setting up the iGEM wiki to upload the local code
iGEM already provides the teams with a default wiki style.
This style can be perfectly used to fully document the iGEM projects in a wiki and fulfill the most important objective of the wiki derivable.
However, most teams style their wikis in a different way to create a distinctive look for their project.
Hence, the first step is removing the default wiki styles to upload the personalized ones.
In this tutorial you will learn how to do so and how to start uploading the content of our wiki.
Uploading the local wiki to the iGEM wiki server
After learning how to edit the wiki from the very beginning and how to adapt it to the required iGEM format, it is time to upload the local wiki to the iGEM wiki server to make it public.
However, it is not as immediate as it may seem. In this tutorial, you will learn how to adapt the local version of the wiki to the iGEM wiki server, how to upload the stylesheet and script files and how to adapt your wiki to revert some styles from load.php that are applied by default.
Finally, you will have your local wiki uploaded to the iGEM server so that everybody can learn from your iGEM project!