Skip to content

Latest commit

 

History

History
88 lines (59 loc) · 7.97 KB

Goals.adoc

File metadata and controls

88 lines (59 loc) · 7.97 KB
Raw

Goals of this User Manual

If we want to create a decent user manual, we need t understand why is it needed, who is going to use it and what do they expect. Let’s first try to see who and why would want to read the user manual and what would they need to be satisfied with their experience. ## Who will read it - and what for?

  • Potential new experienced users - to determine if Zyn-Fusion is the right tool for them, to see the limitations and possibilities of Zyn-Fusion - to see if it’s worth dedicating time and money to integrate it in their workflow,

  • Potential new inexperienced users - to see what they could learn and if Zyn-Fusion is not too difficult for them,

  • Existing users - to find a detailed explanation of how a particular function of the synthesizer works, that they have come by but are not sure what it does,

  • Existing users - to understand why they are not getting expected results from their actions,

  • Existing users - to discover new possibilities that are not immediately obvious from looking at the user interface.

What should we do to satisfy our readers?

Let’s list key features that will make the user manual helpful and a joy to read.

  1. Searchability - the content needs to be clearly divided into sections and easy to find. Chapters and subchapters are a tool for that. The chapter names should be as searchable as possible. Avoid chapter titles like You won’t believe what this does…​ but rather use titles like Frequency modulation. We want users asking questions abount ZynAddSubFX in DuckDuckGo to land here.

  2. Accessibility - the content should be as easy to absorb by inexperienced users as possible. This however has to be balanced against the needs of experienced users - we can’t have "pro" and "noob" editions of the manual. If necessary - basic concepts should be explained in additional frames or chapters to make it easier for experienced users to skip them, but still - to provide such information for the less experienced, or less hurried users if they need or want it. This also means that any specilized language that will be used should be explained within the document somewhere. It could be a Glossary at the end of the document - to avoid putting all the definitions directly into the text - as it could be distracting for the experienced users).

  3. Structure - the manual usually will be subject to random access. However if a user decides to study it from the first page to the last - the experience should still be smooth and fulfilling. Hence the basic information should be presented first, to be later extended with detail that could be confusing at first glance. Broad strokes, first, minute details later.

  4. Linking - references between chapters like more about this in chapter 27.3 or as you probably remember from chapter 8 (for users who jump around a lot and didn’t read the chapter 8 first) are a good way to help users find what they might want to learn other things along the way. It’s letting them know that there’s more information they could obtain if they wish. A manual is in a way a wiki - it can and should be linking to itself. It should allow the users to go on an exciting journey of discovery, it should provide leads for them to follow if they please. We all know the thrill of reading through Wikipedia articles deeper and deeper until we forgot why came here in the first place. The Zyn-Fusion user manual should allow users to dive into it in a similar way.

  5. Visual consistency - once the users have learned how the text and images are formatted and what these visual cues mean, they should never have to re-learn that for this user manual. This is a sign of professionalism and polish. The visual style should also be consistent with the official Zyn-Fusion website. Color schemes, fonts, frames, buttons - let’s give the users a feeling of this all belonging to the same universe.

Technical solutions

Screenshots pipeline

The visual consistency requires a repeatable way to prepare and annotate GUI screenshots. Because the GUI may and will change I (unfa) would advise to prepare a workflow that would allow updating the screenshots with minimal manual effort. The pipeline could be as follows:

Approach 1: directories for different types of data

  1. A directory to keep raw PNG screenshots [A] - a tool like Shutter could be used for capturing these.

  2. A directory to keep SVG files referencing the raw screenshots and adding annotations [B] - the SVG files could crop the whole Zyn-Fusion window and focus on a specific part to allow this to be defined in the SVG file and make replacing screenshots easier (just screenshot the whole window at a specified size.

  3. A directory to keep annotated PNG screenshots [C] - exported from the SVG files

  4. A directory to keep lossly compressed JPG or size-reduced PNG versions (D) of the annotated PNG screenshots [C] - converted with Imagemagick or PNGcrush, or other tools.

  5. A Bash (or Python, or whatever you want) script to render SVG files to PNG and then convert them to JPG or downsized PNG files for distribution.

Updating a screenshot would require:

  1. Taking a new screenshot of a required setup of the GUI (whole window).

  2. Updating the appropriate SVG file to change cropping and annotations

  3. Running the shell script to generate PNG and JPG files (could be selectable to avoid unnecesarry processing of unchanged content)

This could also allow different people to take screenshots and annotate them.

To keep the pipeline smooth we need to define clear and repeatable way to take screenshots that will not break. I (unfa) would propose to use command line import utility, as it will ignore window decoration and hence - make the screenshots taken by different people consistent, regardless of their graphical environment or system configuration:

$ import -window "ZynAddSubFX 3.0.3" Zyn.png
$ display Zyn.png

As long as the default Zyn-Fusion window size (or proportions are not going to change we can simply run zynaddsubfx to prepare a screenshot.

If this is subject to change we could override the window size with another command.

Possible problem: this pipeline is Linux-specific

TODO: how the screenshots will be referenced or embedded in the published documentation?

Approach 2: separate directories for each screenshot (seems like the better option)

This one could make it simpler to process, and also more logical.

Instead of having 4 directories for different types of data, we have a main screenshots directory with subdirectories for eachscrenshot. The subdirectory name is the unique ID for each screenshot:

  • main_window_01

  • addsynth_global_amplitude_01

  • standard_lfo_module

Then each subdirectory would contain a few files with standardized names:

  • A.png - the source screenshot take with import,

  • B.svg - the svg file that provides cropping and annotations,

  • C.png - the bitmap resulting from rendering B.svg,

  • D.png or D.jpg - the filesize-optimized image for publication.

By keeping the filenames the same, we can simply copy a template subdirectory, change it’s name, replace the A.png file, modify the B.svg and run a script to generate C.png and D.png or D.jpg files - minimal effort to update or add new screenshots.

The only thing that changes is the subdirectory name and file contents. Thus referencing a final screenshot could be as easy the following:

<img src="screenshots/main_01/D.png">
<img src="screenshots/addsynth_global_01/D.png">
<img src="screenshots/formant_filter_main_01/D.png">

The standard A B C D names might be changed if something else proves to be more convenient. They key is to keep this consistent after a scheme is picked, or the system will break, will require tons of manual labor and we will gain nothing.