{"id":69495,"date":"2022-12-15T09:00:40","date_gmt":"2022-12-15T09:00:40","guid":{"rendered":"https:\/\/www.cryptocabaret.com\/?p=69495"},"modified":"2022-12-15T09:00:40","modified_gmt":"2022-12-15T09:00:40","slug":"improve-your-documentation-with-javascript","status":"publish","type":"post","link":"https:\/\/www.cryptocabaret.com\/?p=69495","title":{"rendered":"Improve your documentation with JavaScript"},"content":{"rendered":"

Improve your documentation with JavaScript<\/span>
\nJim Hall<\/a><\/span>
\nThu, 12\/15\/2022 – 03:00<\/span><\/p>\n

\n

Open source software projects often have a very diverse user group. 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.<\/p>\n

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 \u2014 dynamic documentation.<\/p>\n

Explore how to add a little JavaScript<\/a> to a web page so the user can choose to display just the information they want to see.<\/p>\n

Structure your content<\/h2>\n

You can use the example where documentation needs to suit both expert and novice users. In the simplest case, you can use a made-up music player called AwesomeProject.<\/p>\n

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>\n

\np<\/span> class<\/span>=<\/span>\"expert reader\"<\/span>><\/span> <\/code><\/span><\/pre>\n
This assigns both the expert class and the reader class. You can create a parallel set of instructions for novices using:<\/p>\n
\np<\/span> class<\/span>=<\/span>\"novice reader\"<\/span>><\/span> <\/code><\/span><\/pre>\n
The complete HTML file includes both paragraphs for novice readers and experts:<\/p>\n
\n


html<\/span> lang<\/span>=<\/span>\"en\"<\/span>><\/span>

head<\/span>><\/span>

title<\/span>><\/span>How to install the software\/<\/span>title<\/span><\/a>><\/span>
\/<\/span>head<\/span><\/a>>

body<\/span>><\/span>

h1<\/span>><\/span>How to install the software\/<\/span>h1<\/span><\/a>>

p<\/span>><\/span>Thanks for installing AwesomeProject! With AwesomeProject,
\nyou can manage your music collection like a wizard.\/<\/span>p<\/span><\/a>>

p<\/span>><\/span>But first, we need to install it:\/<\/span>p<\/span><\/a>>

p<\/span> class<\/span>=<\/span>\"expert reader\"<\/span>><\/span>You can install AwesomeProject from
\nsource. Download the tar file, extract it, then run:
code<\/span>><\/span>.\/configure ; make ; make install\/<\/span>code<\/span><\/a>>\/p<\/span><\/a>>

p<\/span> class<\/span>=<\/span>\"novice reader\"<\/span>><\/span>AwesomeProject is available in
\nmost Linux distributions. Check your graphical package manager and search for AwesomeProject to install it.\/<\/span>p<\/span><\/a>>

\/<\/span>body<\/span><\/a>>

\/<\/span>html<\/span><\/a>><\/div><\/div><\/pre>\n
This sample HTML document doesn’t have a stylesheet associated with it, so viewing this in a web browser shows both paragraphs:<\/p>\n
\n
  \"Image<\/div>\n
Image by: <\/span><\/p>\n
(Jim Hall, CC BY-SA 4.0)<\/p>\n<\/div>\n<\/article>\n
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:<\/p>\n
\n


html<\/span> lang<\/span>=<\/span>\"en\"<\/span>><\/span>

head<\/span>><\/span>

title<\/span>><\/span>How to install the software\/<\/span>title<\/span><\/a>><\/span>

style<\/span>><\/span>

\n.reader {
\nbackground-color: ghostwhite;
\n}

\n.expert {
\ncolor: darkred;
\n}

\n.novice {
\ncolor: darkblue;
\n}

\/<\/span>style<\/span><\/a>>

\/<\/span>head<\/span><\/a>>

body<\/span>><\/span>

h1<\/span>><\/span>How to install the software\/<\/span>h1<\/span><\/a>><\/div><\/div><\/pre>\n
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:<\/p>\n
\n
  \"Image<\/div>\n
Image by: <\/span><\/p>\n
(Jim Hall, CC BY-SA 4.0)<\/p>\n<\/div>\n<\/article>\n
\n
More great content<\/div>\n
\n
Free online course: RHEL technical overview<\/a><\/div>\n
Learn advanced Linux commands<\/a><\/div>\n
Download cheat sheets<\/a><\/div>\n
Find an open source alternative<\/a><\/div>\n
Explore open source resources<\/a><\/div>\n<\/p><\/div>\n<\/p><\/div>\n
Add JavaScript controls<\/h2>\n
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<\/code> 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<\/code> to each of the elements with the class you want to display:<\/p>\n
\n
script><\/span>
\nfunction readerview(<\/span>audience)<\/span> {<\/span>
\n\u00a0 var list, item;<\/span>
\n\u00a0 \/\/ hide all class=\"reader\"<\/span>
\n\u00a0 list =<\/span> document.getElementsByClassName<\/span>(<\/span>\"reader\"<\/span>)<\/span>;<\/span>
\n\u00a0 for<\/span> (<\/span>item =<\/span> 0<\/span>;<\/span> item  list.length<\/span>;<\/span> item++<\/span>)<\/span> {<\/span>
\n\u00a0 \u00a0 list[<\/span>item]<\/span>.style<\/span>.display<\/span> =<\/span> \"none\"<\/span>;<\/span>
\n\u00a0 }<\/span>
\n\u00a0 \/\/ show all class=audience<\/span>
\n\u00a0 list =<\/span> document.getElementsByClassName<\/span>(<\/span>audience)<\/span>;<\/span>
\n\u00a0 for<\/span> (<\/span>item =<\/span> 0<\/span>;<\/span> item  list.length<\/span>;<\/span> item++<\/span>)<\/span> {<\/span>
\n\u00a0 \u00a0 list[<\/span>item]<\/span>.style<\/span>.display<\/span> =<\/span> \"block\"<\/span>;<\/span>
\n\u00a0 }<\/span>
}<\/span>
<\/span>script><\/span><\/span><\/span><\/span><\/div><\/div><\/pre>\n
To use this JavaScript in the HTML document, you can attach the function to a button. Since the readerview <\/code>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:<\/p>\n
\n


html<\/span> lang<\/span>=<\/span>\"en\"<\/span>><\/span>

head<\/span>><\/span>

title<\/span>><\/span>How to install the software\/<\/span>title<\/span><\/a>><\/span>

style<\/span>><\/span>

\n.reader {
\nbackground-color: ghostwhite;
\n}

\n.expert {
\ncolor: darkred;
\n}

\n.novice {
\ncolor: darkblue;
\n}

\/<\/span>style<\/span><\/a>>

\/<\/span>head<\/span><\/a>>

body<\/span>><\/span>

script<\/span>><\/span>

\nfunction readerview(audience) {
\n\u00a0 var list, item;

\n\u00a0 \/\/ hide all class=\"reader\"

\n\u00a0 list = document.getElementsByClassName(\"reader\");

\n\u00a0 for (item = 0; item )<\/span> {<\/span>

 \u00a0 \u00a0list[<\/span>item]<\/span>.style<\/span>.display =<\/span> \"none\"<\/span>;<\/span>
 \u00a0}<\/span><\/span>

 \u00a0\/\/<\/span> show all class<\/span>=<\/span>audience<\/span>

 \u00a0list =<\/span> document.getElementsByClassName(<\/span>audience)<\/span>;<\/span>

 \u00a0for<\/span> (<\/span>item =<\/span> 0<\/span>; item )<\/span> {<\/span>

 \u00a0 \u00a0list[<\/span>item]<\/span>.style<\/span>.display =<\/span> \"block\"<\/span>;<\/span>
 \u00a0}<\/span><\/span>

}<\/span><\/span>

\/<\/span>script<\/span><\/a>>

h1<\/span>><\/span>How to install the software\/<\/span>h1<\/span><\/a>>

nav<\/span>><\/span>

button<\/span> onclick<\/span>=<\/span>\"readerview('novice')\"<\/span>><\/span>view novice text\/<\/span>button<\/span><\/a>>

button<\/span> onclick<\/span>=<\/span>\"readerview('expert')\"<\/span>><\/span>view expert text\/<\/span>button<\/span><\/a>>

\/<\/span>nav<\/span><\/a>>

p<\/span>><\/span>Thanks for installing AwesomeProject! With AwesomeProject,
\nyou can manage your music collection like a wizard.\/<\/span>p<\/span><\/a>>

p<\/span>><\/span>But first, we need to install it:\/<\/span>p<\/span><\/a>>
p<\/span> class<\/span>=<\/span>\"expert reader\"<\/span>><\/span>You can install AwesomeProject from
\nsource. Download the tar file, extract it, then run
code<\/span>><\/span>.\/configure ; make ; make install\/<\/span>code<\/span><\/a>>\/p<\/span><\/a>>

p<\/span> class<\/span>=<\/span>\"novice reader\"<\/span>><\/span>AwesomeProject is available in
\nmost Linux distributions. Check your graphical package
\nmanager and search for AwesomeProject to install it.\/<\/span>p<\/span><\/a>>

\/<\/span>body<\/span><\/a>>

\/<\/span>html<\/span><\/a>><\/div><\/div><\/pre>\n
\u00a0<\/p>\n
With these controls in place, the web page now allows the user to select the text they want to see:<\/p>\n
\u00a0<\/p>\n
\n
  \"Image<\/div>\n
Image by: <\/span><\/p>\n
(Jim Hall, CC BY-SA 4.0)<\/p>\n<\/div>\n<\/article>\n
Clicking either button will show just the text the user wants to read. For example, if you click the \u201cview novice text\u201d button, then you’ll see just the blue paragraph:<\/p>\n
\n
  \"Image<\/div>\n
Image by: <\/span><\/p>\n
(Jim Hall, CC BY-SA 4.0)<\/p>\n<\/div>\n<\/article>\n
Clicking the \u201cview expert text\u201d button hides the novice text and shows only the expert text in red:<\/p>\n
\n
  \"Image<\/div>\n
Image by: <\/span><\/p>\n
(Jim Hall, CC BY-SA 4.0)<\/p>\n<\/div>\n<\/article>\n
Extend this to your documentation<\/h2>\n
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.<\/p>\n<\/div>\n
\n
Make your open source project documentation dynamic so it appeals to users of all experience levels.<\/p>\n<\/div>\n
\n
\n
  \"pink<\/div>\n
Image by: <\/span><\/p>\n
Original photo by\u00a0Marco Tedaldi. Modified by Rikki Endsley.\u00a0CC BY-SA 2.0.<\/p>\n<\/div>\n<\/article>\n<\/div>\n
\n
Documentation<\/a><\/div>\n
JavaScript<\/a><\/div>\n<\/p><\/div>\n
What to read next<\/div>\n

\n        \"Creative<\/a>This work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.<\/div>\n
\n
\n
Register<\/a> or Login<\/a> to post a comment.<\/div>\n<\/p><\/div>\n<\/section>\n
Powered by WPeMatico<\/a><\/small><\/p>\n","protected":false},"excerpt":{"rendered":"
Improve your documentation with JavaScript Jim Hall Thu, 12\/15\/2022 – 03:00 Open source software projects often have a very diverse user group. 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 […]<\/p>\n","protected":false},"author":1,"featured_media":69496,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[307],"tags":[],"class_list":["post-69495","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-open-source"],"_links":{"self":[{"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/posts\/69495","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=69495"}],"version-history":[{"count":0,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/posts\/69495\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/media\/69496"}],"wp:attachment":[{"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=69495"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=69495"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=69495"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}