Write dynamic web documentation with javascript
With a little javascript, you can create documentation that adjusts to your reader's preferences.
Projects can have very diverse user groups. Some users might be very adept at using the system and need very little documentation. For these power users, documentation might only need to be reminders and hints, and can include more technical information such as commands to run at the shell. But other users may be beginners. These users need more help in setting up the system and learning how to use it.
Writing documentation that suits both user groups can be daunting. The website's documentation needs to somehow balance "detailed technical information" with "providing more overview and guidance." This is a difficult balance to find. If your documentation can't meet both user groups, consider a third option: dynamic documentation.
Structure your content
Let's explore how to add a little javascript to a web page so different users can choose to display just the information they want to see. This dynamic documentation provides novice computer users with an easier learning curve, while allowing expert users to see the more advanced commands to do the work.
For our example, let's write an installation document for a made-up open source music player app called Play My Music. Most users will likely want to install this using a pre-built "package" for their system, while experts might prefer to compile the program on their own.
You can write a short installation document in HTML that provides instructions for both experts and novices by using the class feature in HTML. For example, you can define a paragraph intended for experts by using:
<p class="expert reader"> This assigns both the expert class and the reader class. You can create a parallel set of instructions for novices using:
<p class="novice reader"> The complete HTML file includes both paragraphs for novice readers and experts:
<!DOCTYPE html>
<html lang="en">
<head>
<title>How to install the software</title>
</head>
<body>
<h1>How to install the software</h1>
<p>Thanks for installing Play My Music! With Play My Music,
you can manage your music collection like a wizard.</p>
<p>But first, we need to install it:</p>
<p class="expert reader">You can install Play My Music
from source. Download the tar file, extract it, then run:
<code>./configure ; make ; make install</code></p>
<p class="novice reader">Play My Music is available in
most Linux distributions. Check your graphical package
manager and search for Play My Music to install it.</p>
</body>
</html>This sample HTML document doesn't yet have a stylesheet associated with it, so viewing this in a web browser shows both paragraphs:
Add styles to highlight the content
We can apply some basic styling to the document to highlight any element with the reader, expert, or novice classes. To make the different text classes easier to differentiate, let's set the reader class to an off-white background color, expert to a dark red text color, and novice to a dark blue text color:
.reader {
background-color: ghostwhite;
}
.expert {
color: darkred;
}
.novice {
color: darkblue;
}These styles help the two sections stand out when you view the page in a web browser. Both paragraphs with the installation instructions have an off-white background color because they both have the reader class. The first paragraph uses dark red text, as defined by the expert class. The second installation paragraph is in dark blue text, from the novice class:
Add javascript to control the view
With these classes applied, you can add a short JavaScript function that shows just one of the content blocks. One way to write this function is to first set display:none to all of the elements with the reader class. This hides the content so it won't display on the page. Then the function should set display:block to each of the elements with the class you want to display:
<script>
function readerview(audience) {
var list, item;
// hide all class="reader"
list = document.getElementsByClassName("reader");
for (item = 0; item < list.length; item++) {
list[item].style.display = "none";
}
// show all class=audience
list = document.getElementsByClassName(audience);
for (item = 0; item < list.length; item++) {
list[item].style.display = "block";
}
}
</script>To use this JavaScript in the HTML document, you can attach the function to a button. Since the readerview function takes an audience as its parameter, you can call the function with the audience class that you want to view, either novice or expert:
<!DOCTYPE html>
<html lang="en">
<head>
<title>How to install the software</title>
<style>
...
</style>
</head>
<body>
<h1>How to install the software</h1>
<nav>
<button onclick="readerview('novice')">view novice text</button>
<button onclick="readerview('expert')">view expert text</button>
</nav>
<p>Thanks for installing Play My Music! With Play My Music,
you can manage your music collection like a wizard.</p>
<p>But first, we need to install it:</p>
<p class="expert reader">You can install Play My Music
from source. Download the tar file, extract it, then run:
<code>./configure ; make ; make install</code></p>
<p class="novice reader">Play My Music is available in
most Linux distributions. Check your graphical package
manager and search for Play My Music to install it.</p>
<script>
...
</script>
</body>
</html>With these controls in place, the web page now allows the user to select the text they want to see:
Clicking either button will show just the text the user wants to read. For example, if you click the “view novice text” button, then you'll see just the blue paragraph:
Clicking the “view expert text” button hides the novice text and shows only the expert text in red:
If your project requires you to write multiple how-to documents for different audiences, consider using this method to publish once and read twice. Writing a single document for all your users makes it easy for everyone to find and share the documentation for your project. And you won't have to maintain parallel documentation that varies in just the details.
Jim Hall is an open source software advocate and technical writer. At work, Jim is CEO of Hallmentum, an IT executive consulting company that provides hands-on IT Leadership training, workshops, and coaching.