John's "Gold Star for Documentation" Awards

Plugins & Modules
21

Long overdue, I think. Gold Star to…

:star2: Bogaudio :star2:

This started out with me viewing Tiny VCV Rack patches - #121 by tinyvcvpatches

I saw that there was a dual Sample & Hold module in the patch but, apparently, not sampling anything, since there was nothing plugged into then Inputs. So, I downloaded the patch to inspect it more carefully, and it still made no sense. I finally decided to RTFM and – lo and behold – for that module it clearly says:

If nothing is connected to an IN port, sampling for that channel is normalled to an internal white noise source with range 0-10V. Alternative options for the normal source noise type and range are available on the context (right-click) menu. The normal source selection applies to both channels.

It all made sense now.

3 Likes
22

I’ve always wanted a gold star. I guess you need at least one line that says what it does?

23

And it has to be more helpful than saying “emulates the Pre-CBS Mooglaheim 420 Encabulator”.

24

good point. You know, you have been doing this “gold star” for about a year. It seems that there some devs who would like some constructive feedback on their attempts at documentation. But you haven’t been super forthcoming. Shy?

25

Ah heck, you know whut?

:star2:Squinky Labs :star2: gets a gold star too.

Several features that caught my eye:

  • For at least one module (“4X4”), there is a “definition of terms” given near the top.
  • Most have something like what I would call “application notes” to get you started. I used to love that about books like the Texas Instruments “TTL Data Book”.
  • The occasional block diagram.
  • Within Rack, the “right-click Info/User manual” link takes you to a page dedicated to just that module.
  • Descriptions of how polyphony is handled.

So . . . Huzzah!

2 Likes
26

Um . . . It might be mistaken for volunteering to do the documentation? Besides, even if asked for such feedback, it would have to be for plugins I’m likely to want to use, and I’d prefer to reply in a less public manner than in this forum.

27

oh, never mind. I see I got my star! thanks!

28

If it helps quench your desire for validation Squinks… I love you for all yer modules - they’re invariably fab. :+1:

1 Like
29

Just remember to keep it concealed when you go walking through shady neighborhoods.

2 Likes
30

What was I thinking? Of course Count Modula gets one.

/^M^\

I couldn’t believe I didn’t do this before. I needed to look up something last night, and noticed how much documentation there was. A 129-page PDF, with clickable entries in the table of contents.

8 Likes
31

So true, straightforward modules with incredible documentation, designed so smartly for VCV rack, I probably use an equal amount of BOG and Count Modula, because they say what they do and do what they say, then you find little treasures like polyphonic Chances and ADDR supplying polyphonic sequencing.

3 Likes
32

I read through Count modulas entire manual before even trying out the modules, when I was still learning about modular. It was an incredible help. I still find myself reading up on Modules I haven’t tried out yet.

5 Likes
33

Anuddah winnah!

[Hey look everybody, it’s Hoshi, from Arakawa Under the Bridge!]

This Gold Star is for RareBreeds. There are only two modules in the Orbits plugin (EUGENE and POLYGENE)…

… but the docs are perfectly clear.

For example:

All manually controlled inputs are also CV controllable.

Length, Hits and Shift have ±5V bipolar CV inputs with a knob for adjusting CV gain. The gain knob ranges from 0 to 1. After gain is applied to the control voltage input it is summed with the current knob setting.

parameter value = knob value + (control voltage input X control voltage gain knob)

Reverse and Invert have Schmitt triggered CV inputs that override the switch settings.

I love that kind of talk.

And the panel display & controls are easy to figure out. (I regard interface design as a species of documentation.)

BTW, I remembered these tonight when I was looking around for a percussion sequencer that was less pedestrian than usual. Instant jazz combo. Just add patch cords.

5 Likes
34

Another Gold Star* to . . . @StochasticTelegraph / Stochastic Telegraph/Mahlen Morris

Highlights:

  • At the end of each module’s description, there are links to other (non-Stochastic Telegraph) modules with similar or related features.
  • On the FUSE front panels (because I consider the layout and appearance of the UI to be part of the documentation) there is a nifty little progress bar, with colours and shapes that remind you what STYLE setting is selected. If you hover over them, you get a numeric count-up and approximate percentage.
  • Also on the front panels - fairly verbose tooltips.

One thing I would change is to apply some offsets to the four scope traces in the FUSE screenshot so that they don’t overlap. Also reduce the vertical scales and increase the time.

☞ N.B. - Superheroine not included.

3 Likes
35

Thanks, @john_rose! I’ve now updated the Fuse Styles image as you suggested, and it is clearer.

I admit to being proud of the Related Modules section and wishing more docs had them. As an incentive for others to include them, I’ll note that they also serve a practical purpose; when I show the users alternatives that might work for their case, it makes it easier to deflect feature requests I don’t feel like doing :stuck_out_tongue_winking_eye:

mahlen

3 Likes
36

I’ve been saving this Gold Star . . .

… For VCV Free Modules. Finally graduated from many “To Dos” to “Here ya go!”.

Some highlighted features:

• Images with example waveforms that show the behaviour of a module under different conditions, such as this one for COMPARE:

https://vcvrack.com/Free/COMPARE_cv.svg

• Functional diagrams, like this one for VCA MIX:

https://vcvrack.com/Free/VCAMIX.svg

• The numerous “Starter Tips” & “Expert Tips” boxes.

• Links to copy for referencing individual module entries. Yes, one could always copy the link from the index, but these save a trip to the top.

(Oh. Pity those SVG images don’t display in this thread.)

7 Likes
37

Hey @john_rose , Great topic, I am only finding it now, thank you for the star on the new VCV diagrams, and thank you for the silver star on Geodesics. I admit these Geodesics modules were a boooold experiment on Ux limits :grinning: we wanted to see what kind of music is made when we give other names to the things we know, do composers use them differently? The names were always defined by the phenomenon that inspired the modules.

For instance, IONS was inspired by the way electrons travels from an atom to another. If you think the playhead of a sequencer as an electron, then the output range can be called “energy”, its quantization has to do with plank constant, and the ability to jump at anyplace can be called a “quantum leap”. Big science faux-pas in these interpretations, I know. We want users to understand how Ionization work to use it, but we do want to make users curious about science.

The big downsize is that it can’t be used without a manual, this is why we made so many energy in the manual. We wanted to see what happen, and we learn a lot from this experiment. The recent Dark energy module has much more conventional naming and it’s for the best.

Anyways, My personal gold star goes to ZZC with the click on control concept! :blush:

8 Likes
38

I must say that I do enjoy watching Ions, Entropia, Pulsars, etc. spinning around, preserving the momentum. It’s mesmerizing.

1 Like
39

@john_rose if you got some spare time I could use some feedback on these new modules, and for sure their documentation!

1 Like
40

Hmm. Okay.

Arpeggiator: I’ll have to wait until I can download it and try it out to see if what I hear is explained by the docs. [Oh - I found it, with Phasepatterns too.] I’d change the CV labels to “V/Oct”. “CV2” is fine though, and your explanation of what it’s for and why the label is so generic makes sense. In the sample patch image, use the same colour cables for a given signal type throughout the patch, like red for audio, yellow for V/Oct, blue for gates & triggers, green for modulators, etc. (Is that Omri Cohen’s usage?)

Harmony: Needs an image on the Manual page too.

Both: Panel design - use the convention of light borders for input jacks and dark borders for output jacks. [later] Oh, wait … I guess you do do that, but the difference between the dark purple and black is so slight that it’s hard to tell. Does the purple actually get darker in the middle, or is it just an illusion? Also, maybe a bit more contrast on the slide switches. I like the knobs though.

Title Case for the longer labels. I like that. Except for “Strig”. Maybe try “STrig”.

I think I broke Phasepatterns. After hitting the RIB button a few times it got stuck at 10 V o/p, even after initializing it. I had to delete it and replace it.

It would be neat to make it repeat indefinitely, and to be able to select much longer (more than 8 beats) patterns. [much later, crawling out of the rabbit hole] Ah. Used Hetrick’s Phasor Generator set to a very low frequency, scale its output to 0.1, and plug that into the Shft input of Phasepatterns. I got patterns over a minute long. Just gotta set the clock bpm to be some multiple of the Phasor frequency such that when the Phasor wraps around from 10V back to 0V you’re not in the middle of a clock cycle. This can be a fun module, being a big Steve Reich fan myself.

One feature to add might be a zero-delayed clock output normalled from CkIn, just so you can easily trace the two clock signals back to the one module, for a tidier-looking patch.

I just noticed this: The name on the panel is “Phase Patterns”, The manual calls it “Phasepatterns”.

That’s all I got for now, but so far the docs seem fairly star-worthy.