Thread Rating:
  • 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Inline Documentation
#1
Been nerdseq'n for a couple of years, only got involved in feature requests around pattern export. I have thanked Thomas many times, but I'll do it again: thanks! You're a wizard.

As background to my user case, I have a lot of obligations and there are long periods where I can't touch music. Nerdseq has been tremendous in that it allows me to create a groove box where a _lot_ of elements are controlled by the Nerd, so I can leave it and come back, but also work on multiple ideas that I can switch between quickly without repatching, so Nerd is acting in part as a massive preset controller. It takes away some of the spontaneity of starting with an unpatched setup, but I have a "b" rack for that and for doing more elemental synthesis. 

Adding the mapping matrix screen has created an entire rabbit hole -- nay, rabbit metaverse -- that is incredibly useful and extends how one can think about the Nerd. It also adds tremendous complexity. Perhaps some day I'll have a single consistent template for all my projects, but the matrix offers so much flexibility that I can't really imagine not using it differently for different works. But that takes the user way beyond menu diving -- there isn't even a menu for one's own matrix code -- so in a few projects I've found myself coming back and then wondering why I'm still hearing a note repeating, or jumping back in the timeline unexpectedly. I'm not talking about debugging, but rather use -- you create something interesting with the mapping matrix that is unique to a project, but different projects use the matrix differently, and so I'm no longer learning an instrument but creating a mutant instrument per composition. A lot of complexity!

What I'm missing -- from before the mapping matrix arrived but even more so now -- is a documentation function. Documentation for code is important, especially for teams, or (in my case) for a time later when you've stepped away from something, and you just need to refresh why you made certain choices or how something works.

To be clear, I recognize that Nerd should NOT turn into Evernote. Wink But is there a way of doing documentation productively? First, for memory and UI reasons I assume that it would have to rely on external files loaded directly to the screen buffer, ie not saved to working memory. Similarly, I'm guessing the texts should not be in the project file but rather pointers to discrete associated files on the SD. I don't know the details of how you're loading from SD, and I know that saving project files pauses playback, so if there's no easy way to avoid blocking on read we can stop right here.

If, on the other hand, there's a lazy/async way of loading, at human (not tick) speed, I would suggest an addition to the FX column which would allow one to specify a file. DOCU 001 would be doc1.txt on the sd in the project folder, DOCU 002 doc2.txt, etc. Hitting OK on the FX value would load the text to view, up and down arrows could scroll notes and left and right scroll between texts. Shift OK would open a text to edit.

I could personally imagine using the NERD arcade-game-style text entry system to write quick texts, but if the texts were saved as text files that would be amazing -- one could edit them externally and load them to the SD, or if using a qwerty keyboard that could accept text in this mode as well. (I will refrain from requesting VIM bindings Wink ) The key point is that reading is somewhat time critical (should load in a second or two), but writing is not. A block on write would be acceptible.

An example text I can imagine leaving my future self:
"CVin1 mappedd -> euclid hats, CVin2 -> vibrato on EnsOsc, CVin4 max repeats island"

Sure, I can read the mapping matrix and follow patch cables to remind myself of all of this, but it takes time and cognitive energy that I may not be able to spare as I'm loading the next song for a performance. 

Similarly, yes one could take and view notes all on a phone. I have made spreadsheets of connections, made notes on my phone, etc. But I'm already looking at the nerdscreen, and again, pausing to look away and manipulate something else is suboptimal.

Finally, while a single text per song would be a huge help, I like the idea of up to 256 notes/project, as then the texts can be specific to parts of a project. I could see having a basic refresher DOCU text at the top of the song, then if the mapping matrix or interactions get tricky in a particular island, I'd have a more specific text adjacent to that island.
Nerd (especially with other modules) is approaching the complexity of a Max or a Supercollider, and it deserves to have documentation! Thanks for coming to my Nerd Talk.
Reply
#2
I’ve been missing some kind of documentation functionality too. I now try to use pattern names for that purpose, but the character count is often too limiting. I do like that it is specific to the pattern in question (pattern name duh :-) ). And I do understand that it is so limited because of memory size.

So anything in the direction of what proxemics suggests would indeed be a huge help.

Maybe an intermediate idea: could we give up some matrix lines for documentation purposes? Like, instead of the commands, a couple of characters (whatever fits in memory of one or two lines?)
Reply
#3
Thanks for the input and I totally understand and agree with every word you say.
Let's brainstorm about it so it can be both usable, practical and would work also with multiple projects while taking me as less as possible development time.
I threw in some things that come to my head which needs attention for that for sure and some insights:
- Included in the project file is not possible for memory reasons (all text must be available in the memory for any project save)
- Excluded from the project would possibly create a hole since a doc which might not be available anymore which is linked somehow
- Is a FX the good place to access the docu? I don't really think so. Maybe the Nerd Menu would be a better place
- I can load text on the fly and most probably seamless and do a simple text viewer (simple as in really simple, drawing only pages and only be able to change between pages from up>down). The reason of the simplicity is 1st making it more advanced takes quite some development time. Editing is also a bit tricky. Maybe easy if I would reduce it to one page but getting more tricky if I would have multiple pages as I need to load everything into memory then...and I can't remember the times when I had enough memory to do stuff :-)
Seeking in the file here is possible but crazy to implement. My time is more than limited and I don't think getting too deep here is too important.
However, a simple solution which would meet most of the requirements would definitely be worth the time. QWERTx keyboard editing is also possible and maybe the best and only solution (beside external editing) as I would need to write a deeper on screen keyboard editor else. It is possible of course, but the current keyboard takes already 1/2 of the screen height and being able to edit a full page (which would probably be 3/4 of the screen) would involve scrolling again.
- How to define which file should be viewed in an easy way (Maybe 3 kind of docu depending on the current screen and row..if you are on the sequencer screen row 01 then it would use PROJECTFILENAME-SEQ-DOCU-01.txt as the filename. Pattern screen row 1F would be PROJECTFILENAME-PAT-DOCU-1F.txt and mapping row 04 would be PROJECTFILENAME-MAP-DOCU-04.txt. Just an idea, all could be accessed easily from the Nerd Menu. Marking any row that there is a docu available is not possible.

I am sure I can find many more issues on the way...but some solution should be possible.
PLEASE use the search function if something have been asked or discussed before.
Every (unnessesary) forum support means less time to develop! But of course, i am here to help!  Smile
Reply
#4
(04-11-2024, 08:42 AM)XORadmin Wrote: Thanks for the input and I totally understand and agree with every word you say.
Let's brainstorm about it so it can be both usable, practical and would work also with multiple projects while taking me as less as possible development time.
I threw in some things that come to my head which needs attention for that for sure and some insights:
- Included in the project file is not possible for memory reasons (all text must be available in the memory for any project save)
- Excluded from the project would possibly create a hole since a doc which might not be available anymore which is linked somehow
- Is a FX the good place to access the docu? I don't really think so. Maybe the Nerd Menu would be a better place
- I can load text on the fly and most probably seamless and do a simple text viewer (simple as in really simple, drawing only pages and only be able to change between pages from up>down). The reason of the simplicity is 1st making it more advanced takes quite some development time. Editing is also a bit tricky. Maybe easy if I would reduce it to one page but getting more tricky if I would have multiple pages as I need to load everything into memory then...and I can't remember the times when I had enough memory to do stuff :-)
Seeking in the file here is possible but crazy to implement. My time is more than limited and I don't think getting too deep here is too important.
However, a simple solution which would meet most of the requirements would definitely be worth the time. QWERTx keyboard editing is also possible and maybe the best and only solution (beside external editing) as I would need to write a deeper on screen keyboard editor else. It is possible of course, but the current keyboard takes already 1/2 of the screen height and being able to edit a full page (which would probably be 3/4 of the screen) would involve scrolling again.
- How to define which file should be viewed in an easy way (Maybe 3 kind of docu depending on the current screen and row..if you are on the sequencer screen row 01 then it would use PROJECTFILENAME-SEQ-DOCU-01.txt as the filename. Pattern screen row 1F would be PROJECTFILENAME-PAT-DOCU-1F.txt and mapping row 04 would be PROJECTFILENAME-MAP-DOCU-04.txt.  Just an idea, all could be accessed easily from the Nerd Menu. Marking any row that there is a docu available is not possible.

I am sure I can find many more issues on the way...but some solution should be possible.

Thanks for your quick reply! I may not always be so quick but I'm in it for the long haul! Wink

>- Included in the project file is not possible for memory reasons
I suspected as much.

>-Excluded from the project would possibly create a hole since a doc which might not be available anymore which is linked somehow
Yes this is a danger. As long as it soft-failed, though, I suspect people who separate their files by mistake could figure it out and fix it.

>- Is a FX the good place to access the docu? I don't really think so. Maybe the Nerd Menu would be a better place
My motivation was to be able to have inline comments: like // rather than a big /* block */. Nerd Menu can work too, but comments specific to a place (that would get copied and pasted to move with notes and FX) seems optimal? Row references in filenames is a good compromise, but would that be "smart" loading? Like, if you select "doc" from the nerd menu in a pattern row, would it autoload the specific doc for the row you are on, or would you just find it from a list? If the latter, would it rename if you nudged the row up or down? If the latter, I buy the idea 100%. But if nudging a row up or down would require renaming the document (or having the wrong association) I'd be concerned.

> Seeking in the file here is possible but crazy to implement
All good. Entering text from keyboard is okay! Not having full Emacs is okay! Code comments are supposed to be simple.

> Marking any row that there is a docu available is not possible.
Okay, but I guess that's another argument for FX, where you could see DOCU (or CMNT)?

I guess my proposal was imagining FX to be a very fine-grained documentation. Another way of looking at it is that if the Mapping Matrix is what pushes the need for documentation over the edge, that's one place where just a single document would be really helpful. So hitting Nerd Menu would have the option: Comment (Map). Another would be project level, where in the Project Menu there would be a Comment (Proj). Others might be track (cursor on track) and pattern (within pattern screen). Just those four would (I suspect) solve most problems. 

Pattern numbers don't change when they are moved within the project. I move rows around all the time, so I suspect row comments lead to more edge conditions... leaving rows out could be fine. But I could imagine wanting to document something tricky in a row FX, and then the file names would be wrong when you moved it. Similarly with patterns, what happens to the comment when you clone a pattern? Does it clone a copy of the document and rename it? 

This is all a lot of work and decisions, but clearly you are good at both! Thanks again for considering this.
Reply


Forum Jump:


Users browsing this thread: 1 Guest(s)