Version-adaptive documentation: Difference between revisions

From GNU Radio
Jump to navigation Jump to search
mNo edit summary
(revised screenshots for end of Phase 1)
Line 11: Line 11:
* Create a test page with sections which can be hidden, based on a 'data-vad' attribute.
* Create a test page with sections which can be hidden, based on a 'data-vad' attribute.
* Create a form to enter a Version selection.
* Create a form to enter a Version selection.
* Store the Version selection in a user cookie.
* Before displaying the page, execute a script to show or hide sections based on the Version selection.
* Before displaying the page, execute a script to show or hide sections relevant to the Version selection.


<h4>Test results</h4>
<h4>Test results</h4>
----
----
<p>All versions selected.</p>
<p>Page before any selections are made (i.e. all information is shown).</p>
[[File:Phase1_all.png|326px]]
[[File:Phase1_all.png|800px]]
----
----
<p>Version 3.9 selected.</p>
<p>Version selection before clicking 'Submit'.</p>
[[File:Phase1_3-9.png|329px]]
[[File:Gr_version_select.png|799px]]
----
----
<p>Sample version selection menu added to bottom of Navigation pane</p>
<p>Versions 3.9 and 3.10 selected. Note that the section for 3.8 is not shown (hidden).</p>
[[File:Gr_version_select.png]]
[[File:Phase1_3-9.png|799px]]


<h4>Conclusions</h4>
<h4>Conclusions</h4>
Line 41: Line 40:


* Use a 'test' MediaWiki.
* Use a 'test' MediaWiki.
* Put a version pull-down menu below the "Tools" group in the left-hand Nav section; store the selection in the user&apos;s browser localStorage.
* Put a version selection menu below the "Tools" group in the left-hand Navigation section.
* Create a test page with HTML `<sections>` which can be hidden, based on a 'data-vad' attribute.
* Create a test page with HTML `<sections>` which can be hidden, based on a 'data-vad' attribute.
* Embed a JavaScript link at the end of the page HTML to perform the requested selection.
* Embed a JavaScript link at the end of the page HTML to perform the requested selection.

Revision as of 22:48, 1 December 2022

Concept

I am looking into the possibility of making certain pages of our Wiki be adaptive to the user's GNU Radio version (or desired version) so that sections which don't apply would be hidden. This would make cleaner page presentations and reduce the clutter of unrelated information.

Proof of Concept

Phase 1

Plan

  • Emulate MediaWiki with a local nodeJS program to allow non-destructive testing.
  • Create a test page with sections which can be hidden, based on a 'data-vad' attribute.
  • Create a form to enter a Version selection.
  • Before displaying the page, execute a script to show or hide sections based on the Version selection.

Test results


Page before any selections are made (i.e. all information is shown).

Phase1 all.png


Version selection before clicking 'Submit'.

Gr version select.png


Versions 3.9 and 3.10 selected. Note that the section for 3.8 is not shown (hidden).

Phase1 3-9.png

Conclusions

  1. I have found that this methodology for hiding sections of a document is relatively easy.
  2. There are several groups of pages which might benefit from this method:
    1. Block docs
    2. Tutorials
    3. Installation instructions
  3. Specific examples are:
    1. QT_GUI_Chooser
    2. Packet_Communications
    3. LinuxInstall

Phase 2

Plan

  • Use a 'test' MediaWiki.
  • Put a version selection menu below the "Tools" group in the left-hand Navigation section.
  • Create a test page with HTML `<sections>` which can be hidden, based on a 'data-vad' attribute.
  • Embed a JavaScript link at the end of the page HTML to perform the requested selection.