(07-11-2024, 07:52 PM)undercarbonated Wrote: My NerdSEQ is showing up today thanks to Perfect Circuit, so I'll probably spend time using it now instead of making trouble reformatting the manual.
If you are into the idea of the community contributions, there could be a build process that went from the individual files to a single PDF, so it would be possible to still have a single point where updates are made and then a web and a PDF manual both built from the one source. A community of creative nerds like you have here could be helpful in making the upkeep easier for you.
I'll set the repo to private to avoid any chance of confusion.
I would be interrested but I got some concerns. One is if a proper layout can be guaranteed for both the online and the PDF without drastically increasing the amount of pages.
Also could the internal links/cross references still be possible and updated in a smart way including the auto indexing? Who should be allowed to edit...
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!
The links/cross references are certainly possible. They didn't come through in the automated conversion, but they aren't hard to add back. I haven't investigated the possibilities of auto-indexing, but that sounds like a nice improvement. Having a TOC and a topic index both built automatically could reduce toil and provide more value to the reader. Markdown is somewhat limited in its features, so I've been looking at AsciiDoc; I does appear that AsciiDoc has an index feature: https://docs.asciidoctor.org/asciidoc/la...ser-index/.
For editing, I would imagine you would own the repo and people could submit pull requests. You could either approve and merge the requests yourself, or deputize people to do it. If you wanted to have final control over all the changes, you could still have some help in reviewing the incoming requests to filter out low quality and help submitters improve their submissions before you need to review them. Regretfully, pull requests are confusing for users who aren't used to using version control, so this filters out the number of possible helpers.
Your concern about the number of pages is probably the hardest to be certain about. There is a lot to communicate in this manual. In its current state it is already long and fact dense. Reducing the density will likely mean it could end up even longer.
FWIW I find for example the lists of functions for the various pattern types fairly hard to read. It is my impression that this is partly due to the chosen layout. I would expect that readability could be improved by a different layout. I also think that especially w/r to the function lists a restructuring might be helpful.
As it is now there is a lot of overlap and duplicated information. Having a central description/explanation for all functions with information for which pattern types they are available, possibly with link from and to would reduce the amount of repeated text and thus shorten the manual. It would also simplify reading as the reader would not have to cross check "is this the same as for type xyz?" but could just see that.
07-17-2024, 04:04 AM (This post was last modified: 07-17-2024, 05:24 AM by undercarbonated.)
As an example, I have tried to update one section. I have attached a PDF version. It's gone from 2 1/4 pages to 3 pages, but I think it is overall more accessible. I've reworded some sections, but I didn't feel like I had a completely grasp of all the details so left some text as is.
Edit: I've done a second section to show the linking between sections and a TOC. The overall page count for the project section stayed at 3.
There's the hardware and software, both huge endeavors,
Then there's the manual. It's a bottleneck, but it's also your gem in the rough.
I know you often say you don't have the time and money to put into it,
but this documentation is your most significant product.
With a device this complex and interwoven, it's everything.
To make it a less weighty document, maybe approach it as 5 or 6 discrete volumes, and don't worry about cross-indexing.
- Introduction and Overview (what's here, power and possibilities)
- Hardware Reference (Just the boards, wires and voltages and cables, nothing referring to a software release),
- Navigation Basics (getting around, the menu tree, a map, a few simple examples to try, providing positive first success)
- Menus In Depth (vols. 3a and 3b i.e. the hard stuff, but spread out, new features go here in vols. 3c, 3d...),
- Cookbook (Examples, FAQ, cheat sheets, (and please) Light Internals Overview and History of NerdSeq)
Rough copy paste sections from the current manual into separate draft volumes and see how it feels.
Condensing down the paragraphs into dense information nuggets makes the information less potent, not more.
Whitespace is free and you don't even need to make ton of tedious tables if things are just spaced out with good headings.
It's a pdf. Don't treat it like you're saving paper.
Those ADHD adjacent issues mentioned above with the documentation are there for lots of us.
I suspect it's worse that you believe it is.
The hardware is rock solid, the software teases at great functionality, but getting stuck in the mnemonic menu system,
without easy reference at hand, always frustrates me at some point, losing the ideas flow, and I have to move on.
I've got a NerdSeq, Slim Midi, video i/o, and cv board and I so, so, want to use them more,
but it always drags me in the weeds, jumping from page to page, digging for words in paragraphs.
Please fix the docs. Stop adding features, it's enough. That's done. It's great.
All of those jacks on NerdSeq hook up to other things, and I can't dedicate 80% of my focus just on NerdSeq.
You've got to make it easier so people won't be discouraged by all of the wonders you have created here.
--
(07-17-2024, 05:01 AM)tapiocatwilight Wrote: There's the hardware and software, both huge endeavors,
Then there's the manual. It's a bottleneck, but it's also your gem in the rough.
I know you often say you don't have the time and money to put into it,
but this documentation is your most significant product.
With a device this complex and interwoven, it's everything.
To make it a less weighty document, maybe approach it as 5 or 6 discrete volumes, and don't worry about cross-indexing.
- Introduction and Overview (what's here, power and possibilities)
- Hardware Reference (Just the boards, wires and voltages and cables, nothing referring to a software release),
- Navigation Basics (getting around, the menu tree, a map, a few simple examples to try, providing positive first success)
- Menus In Depth (vols. 3a and 3b i.e. the hard stuff, but spread out, new features go here in vols. 3c, 3d...),
- Cookbook (Examples, FAQ, cheat sheets, (and please) Light Internals Overview and History of NerdSeq)
Rough copy paste sections from the current manual into separate draft volumes and see how it feels.
Condensing down the paragraphs into dense information nuggets makes the information less potent, not more.
Whitespace is free and you don't even need to make ton of tedious tables if things are just spaced out with good headings.
It's a pdf. Don't treat it like you're saving paper.
Those ADHD adjacent issues mentioned above with the documentation are there for lots of us.
I suspect it's worse that you believe it is.
The hardware is rock solid, the software teases at great functionality, but getting stuck in the mnemonic menu system,
without easy reference at hand, always frustrates me at some point, losing the ideas flow, and I have to move on.
I've got a NerdSeq, Slim Midi, video i/o, and cv board and I so, so, want to use them more,
but it always drags me in the weeds, jumping from page to page, digging for words in paragraphs.
Please fix the docs. Stop adding features, it's enough. That's done. It's great.
All of those jacks on NerdSeq hook up to other things, and I can't dedicate 80% of my focus just on NerdSeq.
You've got to make it easier so people won't be discouraged by all of the wonders you have created here.
--
A part of what you describe is already like you describe it: Introduction, Overview, Basics to get started etc.
From there it is getting tricky and so far no one could come up with a better solution than what it is now. In the end you got multiple screens with each it's own functionality but much functionality can be cross-used on other screens or with other functionality. The only separation I see is the one to separate between the screens and then through the hardware and side-functionality.
If you got a better idea beside the rough sketch you came up with and without losing any functional detail, please let me know. I am always happy to improve stuff and if I need to 'refactor' anything for that then it would be fine, too. I can already tell you that nothing will change if they no concrete good and detailed proposals. I do focus on the fact that always everything is in the manual and that at the point of a new release. That is often not a thing with other products, even with ones that are much more simple.
I also do focus on adding new features and improving stuff (for free) which makes it possible that still after 7 years I can pay my bills with it. I will keep continuing that at least for a while. And probably many people wouldn't agree with you that I should stop adding features...the feature request thread is the biggest thread on the forum.
Another thing I also went through is that they have been attempts to improve and rewrite the manual by other people multiple times before. In the end it cost me money, hardware and time without any result. It is easy to say that it can be better but it is not easy to make it better. That makes me also very sceptical to give it out of hands as no one has been reliable enough before to finish it so I could continue. I have multiple of these example pages how it could look like...and I was very enthousiastic about them and it ended always with only these example pages.
Anyways, I do agree that there is room for improvements, some things could be explained in a better way and the tons of grammatical issues. I am not sure about a general restructuring. That is probably more something for someone who writes a book about the NerdSEQ rather than a functional manual.
But maybe I am also not too open for these kind of things as I am more a developer than the one who writes the manual. I enjoy developing, I don't really enjoy writing the manual, I am not a graphic, media, industrial designer who can make fancy product flyers...but still I do what I got to do.
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!
Thank you, Thomas, for the clear explanation of your thoughts on this topic. I have a much clearer idea of the landscape and the history here.
I certainly understand your feeling about wanting to work on the product and not the docs. I have been through similar things. You have done most of the work already here, getting all the information down. Writing a manual from scratch is a big job, but taking your existing document and tweaking the formatting and language, feels tractable.
I don't want to cost you any time, money or hardware. I'll work on this quietly. If I can accomplish it, I'll come back to you once I have a completed project which I will hand into your control, with clear details on how to update the content and how to produce the outputs.
This looks to be new from Doepfer. Really nice layout.
It reminds me of ARP's 2600 manual in the 1970's.
Light and airy and intended to be printed and saved, with notes written in it.
A NerdSeq manual section, with these task based walk-thrus
could provide a more confident foundation to push on into the formidable depths.
The Doepfer document has a user's view, not a device's list of features.
And yeah, I know it was expensive to produce. But a bit of this would be wonderful.
This looks to be new from Doepfer. Really nice layout.
It reminds me of ARP's 2600 manual in the 1970's.
Light and airy and intended to be printed and saved, with notes written in it.
A NerdSeq manual section, with these task based walk-thrus
could provide a more confident foundation to push on into the formidable depths.
The Doepfer document has a user's view, not a device's list of features.
And yeah, I know it was expensive to produce. But a bit of this would be wonderful.
It’s a different thing. I would love to have a NerdSEQ cookbook. But indeed I don’t have the funds and young designers which are waiting in the queue to do the job but also know everything about the NerdSEQ. Different thing than a manual though.
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!
One of the difficulties with a Cookbook in this case is NerdSEQ development can progress so fast that when more things like that are produced, they could quickly become outdated.
I think the Cookbook idea is something the user community could maintain since it wouldn't strictly be part of the manual, and that could take some of the burden off of Thomas. When he spends his time on the manual he should be able to focus on clear and direct explanations of the functionality. The rest, how to turn those technical details into musical creativity, we should be able to work out and explain to each other.
I recently revised a very complex document (unrelated to Eurorack) and it went from around 64 pages up closer to 90. But, the people using it praised the change because most of the updates were better spacing, standard sized fonts (12pt instead of mixtures that included 9pt in some places in the old version) clearer directions (less assumptions), and better cross-references, as well as a system of End Notes and Appendix material where some of the detail and "rabbit trails" could be moved out from the main body of the work and referred to there instead.
Sometimes the length of a document can only seem intimidating if it is also messy. I don't think NerdSEQ's manual is "messy" but it is very feature rich. Thomas, you have done a good job with the table of contents, diagrams, and included some very nice extra touches such as a Decimal to Hexadecimal explanation in case any non-nerds try to use NerdSEQ
It is a lot of material, and a daunting task. What you have created requires something more similar to a Dungeons & Dragons Handbook than the manual of a typical Eurorack module. I struggled at first to wrap my mind around some of the concepts, but I'm using it now and hardly ever have to ask for help at this point.
The YouTube demonstration videos are also amazing, and an important supplement to the manual.
As for the paragraph suggestion, I think many parts of the manual are already divided up pretty well into paragraphs. But, due to the nature of the product, sometimes the manual gets to a section where many codes need to be explained all in a list (for example, the trigger values for ratcheting and trigger lengths, or another example, the FX command descriptions.)
Comparing once again to Dungeons and Dragons, this is like when they have a Spellcasting class, and suddenly there is a need to document a tedious list of spells. In the case of D&D, (at least in the 3.5 edition i'm most familiar with) they have decided to relegate Spells to a chapter later in the handbook, that way the class description for a Wizard, Sorcerer, Cleric, etc., can just refer you to the Spells chapter for that material. Because not all spellcasters have the same spells available they even have per-class lists (like, 2nd level Sorcerer Spells) near the front of the Spells chapter, but then all the spells are in alphabetical order after that.
NerdSEQ only has a few things like this, not a lot, but the ones it does have are very lengthy. I'm not sure if migrating them to a later Chapter would be helpful, but it might be a consideration to keep things as simple as possible in the main Chapters (for example where the Pattern screen is explained) and then for the FX column to explain what an FX column is, and then say for complete list of FX for this track type, refer to page x. That way it would keep the instruction moving along and not become bogged down by tables?
I don't know if that would be an improvement or not, though.
