Online documentation guide

Overview

The page is divided into multiple sections: [[top-nav]], [[left-nav]], [[main content]] and [[footer]].

Some of the content pieces are driven from external files to keep design and structure consistent while other sections specific to the page can be updated by editing html of this page itself.

Light weight

The web page is build using w3css which is a light weight version of bootstrap designed by Google. Unlike bootstrap it does not have fancy animations as it does not have a js library but only css. That also means that the page is fast to load and by adding a few simple javascript functions it's functionality can be enhanced. W3css link can be found on footer section of this page for further study.

The benefit of using w3css is to provide mobile first experience to users. The document is responsive and adjusts to all screen sizes to make the page user-friendly.

In addition to it the page also use font-awesome and google fonts to provide nicer user experience.

Printable

The web page is printable and automatically hides certain sections that need not be displayed printed on paper or pdf. It also sets up a cover page to give neat printed document. Go ahead and try print preview this web page to see the difference.

Note some links have a javascript functions that when printed will not be of much use to reader. You can skip printing urls of those links by adding class skipPrint to them.

User form

As a first time user, you will be asked to enter your name so the document knows you when you open it next time. The username is stored in document cookies globally; meaning it can be shared across all documentation. Please note that the cookies are machine and browser specific, which means if you use another machine or switch your browser between IE, Edge etc, you will be asked to enter username again.

Snippets

You can use some of these code snippets to construct documentation.

Code tile

Code tile lets you add code as is to your html document. The code must be wrapped in pre tag. This tag allows you to add your code in multiple lines and retains spacing. Within pre tag add a styled div container where you can simply copy and paste your code just like the example below.

  
  //-----------------------------------
  //SP2016 top bar user image.								
  function getUserImage(){
  //Get image of current user and add to the top nav.
	var imgUrl = MYSITEImgURL + "User%20Photos/Profile%20Pictures/[userid]_LThumb.jpg";
	var u = _spPageContextInfo.userLoginName;
	var userid = u.split("\\")[1];
	imgUrl = imgUrl.replace("[userid]",userid);
	
	return imgUrl;
  }

Code window

The code tile however does not display html tags rather it renders it into the html page. To show html tags you have to escape html first and then add it to the above panel. An easier alternative is to use a textarea wrapper around your code. The textarea below contains the html code for above snippet which is read only but users can copy the code.

  <pre class="w3-panel">
  <div class="w3-code w3-small w3-light-gray w3-card">  //-----------------------------------
  //SP2016 top bar user image.
  function getUserImage(){
  //Get image of current user and add to the top nav.
	var imgUrl = MYSITEImgURL + "User%20Photos/Profile%20Pictures/<<userid>>_LThumb.jpg";
	var u = _spPageContextInfo.userLoginName;
	var userid = u.split("\\")[1];
	imgUrl = imgUrl.replace("<<userid>>",userid);

	return imgUrl;
  }</div>
  </pre>

Short code

Short code is a short hand for [[wrapping some text in a code bubble]]. Just use double square brackets [ [ some text ] ] and text will be automatically wrapped. Ensure there is no space between a pair of square brackets. Also do not enter just one set of brackets like left square bracket only. Double left bracket should end with double right bracket or the code may break the page.

Files list

Files list allows you to add files to your documentation quickly. The list below shows file icons and their relative path.

Font awesome icons

Easily add font awesome icons to your document by adding following code. For font awesome to work, you need to reference required css in head section of a html page. Font awesome is already being referenced in your document and all you need is correct class for the icon tag. Check out the font awesome site for references to icons. Note: examples on the site uses <i></i> tags which could be a compliance issue. Using <span></span> tag is a safer option and works just fine.

A standard icon a large icon and an icon with current theme

Load common html

It is also possible to save a piece of information once and use it multiple times in various documents; allowing you to maintain it at one place. The information is saved in a [[commonHtml.js]] file in [[Documentation/Assets]] folder. Adding it to a javascript file makes it available throught the documentation and permission issues to load files dynamically are avoided when documentation is on local machine.

Note html formatting is preserved for readibility by adding [[\]] backslash character in javascript string. This allows html to be split to multiple lines without breaking javascript code. You can achieve the same using concat function.

Once the piece of information has been created in commonHtml file, it can be referenced in documentation by adding an element e.g. [[div class="modal loadCommonHtml" id="myModal"]]. The id of element must match javascript variable with 'Html' added to the variable [[id="myModal" ... var myModalHtml = '...';]]