EP1000

Website Development

Documentation Techniques

The important function of documentation is to provide a “timely” source of information, so that

Hence a documentation tool should:

Traditional documentation techniques use paper notebooks or journals, however, in this age of sharing information, the portability is at issue.

A good and popular solution to this problem is to use text and create Internet website that can be hosted on the World-Wide-Web.

Text Editors

The choice of using text instead of a proprietary word processor is that text is universal and can be used/edited/hosted/shared on multiple platforms without conversion or loss-of-data.

The characteristics of a good text editor should include

Here are some recommendations:

Website development

A website consists of webpages containing information of what you wish to display or to keep as reference. The advantages of documenting using a website are

For this module, you will create a website that

What is important is that we should pay more attention to the content than how “beautiful”, “interactive” or “aesthetic” your site looks. We are not creating a website that markets a product/information but to share knowledge.

Here are the 4 ways in which you can develop your site together. You are free to choose any method to develop your website, however, you must remember that you need to update your site periodically (as and when) with new information

  1. Pure HTML & CSS
    You start with HTML and write your content, stylize it with CSS to give a consistent look and feel.
    • Advantages
      1. Simple to start, can be very basic.
      2. Design is completely yours to play around with, you have full control
    • Disadvantages
      1. Gets complicated when more pages are added
      2. Difficult to maintain consistency
      3. Difficult to get a consistent design look and feel
    • How-to
      1. Make a simple HTML file with links to your pages.
      2. Use a CSS file to format the layout
      3. Example of basic website
  2. Borrow A Design/Template That Works
    You start with a design that works (e.g. Jake Wright: Learn CSS in 12 minutes). Modify and add whatever you want in HTML (content) and tweak its looks using CSS (Layout).
    • Advantages
      1. Design is professionally looking, just add content.
      2. Don’t need to do much in terms of modification
    • Disadvantages
      1. Need to understand how site is designed to add content.
      2. May need to make changes to maintain consistency
      3. Need knowledge of HTML and CSS
    • How-to
      1. Search the Internet for a HTML/CSS template site that you like
      2. Copy the template to index.html as the starting page
      3. Populate and expand your website.
      4. How to use Jake Wright’s Template

  3. Use Markdown (Pure Markdown)
    Markdown is a light-weight Mark-Up editing language that is good for displaying information. It is ideal for making fast notes, while still maintaining the document very “text-like”. Most documentation sites offer a markdown hosting option.

    Markdown text is first processed by a program (usually python/javascript) into HTML. The HTML is then hosted by the webserver. This process is usually transparent to the user.

    • Advantages
      1. Very text-like, easy to make notes and add information
      2. Can supplement/substitute with HTML if you need more control
      3. github allows direct editing on the server.
    • Disadvantages
      1. Need a hosting service that serves markdown (alternative: MkDocs)
      2. Need to learn Markdown
      3. Website looks very “bare”, “no-frills”, even with themes.
    • How-to
      1. This site is an example of a pure Markdown site.
      2. Surf to the github site for this repository https://github.com/rdorville/EP1000
      3. Use the github code tab to examine the contents
      4. Create a new repo on your github account and enable github pages.
      5. Start with the file “index.md” as the root of your website.

  4. Jekyll themed site (Using Markdown)
    Jekyll is a static site generator which converts Markdown together with other instructions to HTML which is then hosted by the server.

    Mr Chew has kindly provided a template https://skeatz.github.io/web-pk/ which allows you to create a very professional-like site for your project.

    • Advantages
      1. Information is added using Markdown or HTML, easy to edit.
      2. Processing by Jekyll is transparent to the user.
      3. Very professional can change themes.
    • Disadvantages
      1. Need to be hosted on github or a site which can execute Jekyll.
      2. Need to understand how each part of the site is created, like solving a puzzle
    • How-to
      1. I would suggest that you complete the git section (next week) before you attempt this as you need to upload a number of folders and files to your repository (unless you want to do it one at a time)
      2. Download or clone the repository at (https://github.com/skeatz/web-pk) to a new folder.
      3. How-to use web-pk for your website

Assignments

There are 2 assignments for this topic. Both assignments will be graded, however, you will be given appropriate time to complete them.

  1. Assignment 4A HTML, CSS
    This assignment checks that you have an understanding of HTML and CSS. You are required to
    • Watch and replicate Jake Wright’s website (Learn CSS in 12 minutes)
    • Modify the website based on the requirements
    • Save the website as a ZIP file for submission
  2. Assignment 4B Github Website
    Thsi assignment checks that you have created your own website prescence on the Internet. You are required to
    • Create a Github account
    • Convert a project site EP1000 to Github Webpages
    • Use git/Github Desktop to manage the site.

 

Home Home
October 2020