zynaddsubfx / user-manual

User manual (this may or may not get merged into zynaddsubfx/zynaddsubfx's doc dir)
30 stars 10 forks source link

Clean up grammar and formatting - User Interface #11

Closed celestehorgan closed 5 years ago

celestehorgan commented 6 years ago

Grammar and formatting cleanup of the user interface section.

A few notes:

fundamental commented 6 years ago

Looking quickly at the changes, it seems that you're shifting the tone to be what I would consider to be too formal. The document is intended for users to learn from rather than working as a formal specification. As such the intent is to keep a lot of the language conversational as the overly formal nature of the older documents did result in turning away many musicians who were just getting started with various concepts.

fundamental commented 6 years ago

I changed the title case of some titles.

That works fine for me. I've bounced back and forth with respect to those conventions when I've worked on technical writing over the years.

I attempted to add an anchor link to resolve the one issue.. we'll see how it goes

Great :)

I changed the title of this section to "Zyn-Fusion UI overview".

I should be fine with that, though that's going to be an implicit theme throughout the user guide since the goal is to have the vast majority of users using the zyn-fusion interface long term.

Per the notes on the general formal vs conversational tone for the user manual I'd recommend listening to the flow of a segment in one of unfa's tutorials. Consider 9:30-10:30 in https://www.youtube.com/watch?v=GWMlPjpQYbo . In this section the current state of sound synthesis is mentioned, problems that a user can encounter are brought up and there's a motivation for making distinct changes in terms of how they change the user observable output. There's a brief mention of the 'what does X do?', but it is deprioritized compared to 'why do you want X?' and 'how can you use X to help reach your goal?'. I might be belaboring the wrong point, but shifting the language within each section to reflect this difference in tone IMO is a way to create an end document which will hopefully be more usable to end-users.

fundamental commented 5 years ago

bump

fundamental commented 5 years ago

Closing due to inactivity. Feel free to come back and reopen if you're interested.