dev.metalisp.survey/README.org

#+title: dev.metalisp.survey
#+author: Marcus Kammer
#+email: marcus.kammer@mailbox.org

* dev.metalisp.survey

Made with Love ❤️ and Common Lisp

** Disclaimer

Libre software (LS) is often misunderstood as entirely free, including support
and maintenance. While LS is freely available to use, modify, and distribute,
users bear the responsibility for its integration, upkeep, and
troubleshooting. Unlike commercial software, which typically includes support
services, LS relies on community or paid third-party support, if
available. This model empowers users with flexibility and control but requires
a commitment to managing the software effectively. Therefore, adopting LS
demands a proactive approach to handling any issues and ensuring the software
meets organizational needs.

** Introduction

*** Purpose
Efficiently administer and analyze the System Usability Scale (SUS) and Visual Aesthetics of Websites Inventory (VisAWI) questionnaires.

*** Core Features
- Presents questions and collects responses
- Streamlines usability feedback gathering and analysis
- Offers flexible templates for high reusability and adaptability
- Synthesizes data from multiple questionnaires into a single study

*** Key Benefits
- Self-hosted solution for enhanced data protection
- Users have full control over their data
- Valuable for research projects and market research

*** Integration
- Easily integrates with existing websites or software systems

*** Target Sectors
- Research projects
- Market research
- Any field requiring precise data collection and analysis

*** Target Users
1. Disabled (User / UX) Researches (Primary)
2. UX Freelancers (Secondary)
3. Small UX Agencies

** Design Goals

1. *Integration*: The app integrates seamlessly into existing digital
   platforms, enhancing user experience and simplifying data capture.

2. *Reusability and Adaptability*: Customizable templates allow for the
   creation of consistent and repeatable survey formats suitable for various
   applications.

3. *Data Synthesis*: It supports combining data from multiple questionnaires
   into a single study, providing broader and more comprehensive analytical
   insights.

4. *Privacy and Control*: With self-hosting, the software ensures complete data
   sovereignty and enhances privacy, avoiding the need to transfer sensitive
   data to external servers.

5. *Accessibility*: The application is designed following the Web Content
   Accessibility Guidelines (WCAG) provided by WebAIM, ensuring that the survey
   is accessible to all users, including those with disabilities. This includes
   features such as keyboard navigation, screen reader compatibility, and high
   contrast modes to accommodate users with varying needs and abilities.

** Features

1. *Questionnaires*: Questionnaires can be defined using a Domain-Specific
   Language (DSL) developed for dev.metalisp.sbt. The benefit of defining forms
   in files is that they can be versioned using GIT, providing better control
   over changes and updates.

2. *Simplicity*: All data is saved to files, eliminating the need for a
   database. This reduces costs for self-hosting and simplifies the setup and
   maintenance of the application.

** Dependencies
- https://github.com/edicl/hunchentoot
- [[https://code.metalisp.dev/marcuskammer/dev.metalisp.sbt]]
- [[https://code.metalisp.dev/marcuskammer/dev.metalisp.qmetrics]]
** News Feed
- [[https://code.metalisp.dev/marcuskammer/dev.metalisp.survey.rss]]
- [[https://code.metalisp.dev/marcuskammer/dev.metalisp.survey.atom]]
** XMPP (Jabber) Chat
#+begin_example
metalisp@conference.mailbox.org
#+end_example
** Installation instructions
*** Without using Quicklisp                                        :noexport:
**** 1. Install a Common Lisp implementation

   - Ensure you have a Common Lisp implementation installed. Common options
     include SBCL (Steel Bank Common Lisp) and CCL (Clozure Common Lisp). You
     can download and install them from their respective websites:

     - [[http://www.sbcl.org/][SBCL]]
     - [[https://ccl.clozure.com/][CCL]]

**** 2. Set up ASDF

   - ASDF is typically bundled with modern Lisp implementations. However, if
     it's not present, you can download it from [[https://gitlab.common-lisp.net/asdf/asdf][ASDF's repository]].

**** 3. Organize the project directory

   - Place the =dev.metalisp.survey= project in the =~/common-lisp=
     directory. Ensure the directory structure looks like this:

     #+BEGIN_EXAMPLE
     ~/common-lisp/
       └── dev.metalisp.survey/
           ├── dev.metalisp.survey.asd
           └── src/
               └── app.lisp
     #+END_EXAMPLE

**** 4. Configure ASDF to find the project

   - Open your Common Lisp REPL and run the following commands to set up the
     ASDF central registry:

     #+BEGIN_SRC lisp
     ;; Ensure ASDF is loaded
     (require :asdf)

     ;; Add ~/common-lisp to the ASDF central registry
     (push #p"~/common-lisp/" asdf:*central-registry*)
     #+END_SRC

**** 5. Load the project

   - In your REPL, load the project by running:

     #+BEGIN_SRC lisp
     (asdf:load-system :dev.metalisp.survey)
     #+END_SRC

**** 6. Run the project

   - After loading the system, you can run the main function or entry point of
     the project.
     =ml-survey:start=, you would execute:

     #+BEGIN_SRC lisp
     (ml-survey:start)
     #+END_SRC

**** Optional: Example Initialization in .sbclrc

To make the ASDF configuration persistent across REPL sessions, you can add the
setup to your =.sbclrc= file:

1. Edit =.sbclrc=
   - Open (or create) the =.sbclrc= file in your home directory and add the
     following lines:

     #+BEGIN_SRC lisp
     (require :asdf)
     (push #p"~/common-lisp/" asdf:*central-registry*)
     #+END_SRC

2. Reload SBCL
   - The next time you start SBCL, it will automatically include the
     =~/common-lisp= directory in the ASDF central registry.

*** With using Quicklisp

Quicklisp is a highly recommended library manager for Common Lisp capable of
streamlining the process of installing and maintaining libraries. It simplifies
downloading, building, and loading libraries with a minimal fuss and supports
command line interaction.

This guide will demonstrate how to install Quicklisp on both Linux and Windows
operating systems.

**** Why Use Quicklisp?

Quicklisp offers several advantages for Common Lisp development:
- *Ease of Use:* It simplifies the installation process of common Lisp
  libraries, handling dependencies automatically.
- *Extensive Library Collection:* Quicklisp connects to a vast repository of
  libraries, making it easy to find and install almost any library you need for
  a project.
- *Regular Updates:* Quicklisp updates its library list monthly, so you always
  have access to the latest versions.
- *Integration:* It integrates well with many Lisp environments and tools,
  enhancing your development workflow.

**** On Linux

1. *Install a Common Lisp implementation:*
   For example, to install SBCL:
   #+begin_src bash
   sudo apt-get install sbcl
   #+end_src

2. *Download Quicklisp Installer:*
   Open a terminal and run:
   #+begin_src bash
   curl -O https://beta.quicklisp.org/quicklisp.lisp
   #+end_src

3. *Install Quicklisp:*
   With Lisp implementation installed (e.g., SBCL), run:
   #+begin_src bash
   sbcl --noinform --load quicklisp.lisp --eval "(quicklisp-quickstart:install)" --eval "(ql-util:without-prompting (ql:add-to-init-file))" --non-interactive
   #+end_src

**** Load dev.metalisp.survey

1. Clone this repository and dependecies
   #+begin_src shell
     git clone https://code.metalisp.dev/marcuskammer/dev.metalisp.sbt.git ~/quicklisp/local-projects/
     git clone https://code.metalisp.dev/marcuskammer/dev.metalisp.qmetrics.git ~/quicklisp/local-projects/
     git clone https://code.metalisp.dev/marcuskammer/dev.metalisp.survey.git ~/quicklisp/local-projects/
   #+end_src

2. Start sbcl and load dev.metalisp.survey
   #+begin_src lisp
     (ql:quickload :dev.metalisp.survey)
   #+end_src

3. Start the web server
   #+begin_src lisp
     (ml-survey/app:start)
   #+end_src

** Screenshot
[[https://git.sr.ht/~marcuskammer/dev.metalisp.survey/blob/main/screenshot.png]]
** License
*** MIT

Copyright (c) 2024 Marcus Kammer

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.