As you can see, we have decided to have a unified User’s Guide for all the 3 physical interfaces / layouts. You should see a black top-bar with the 3 options at right:
V5 (default)
V4
Touch / mouse
It’s still a work in progress, but i hope it will improve a lot in the next days/weeks.
Please, if you want to collaborate, contact with me or @riban. We would like to keep some style rules, but we have not defined them yet. Still testing things. And yes, we know some things are not working in mobile yet
Hey Jofemodo, this is nice to see. I like the tabs at the top to switch between the versions.
I have a few arturia devices and I think they do a pretty good job with their manuals. It’s a mix of ways you could use the device (like a creative prompt/you should try this!) along with all the factual explanatory stuff.
I also have an Akai and although it feels like it could be written by a robot, it is filled with many snapshots of the UI screens and physical interface and is quite clearly laid out.
When I think about the manuals for my various Korg devices, some are so short they are practically a diagram with some text callout bubbles. It could be because they’re all sort of old devices and they probably didn’t want too many pages to print (in 10 languages!).
Did you think about other manuals that you can use as a reference?
Another thing to consider is a style for the diagrams/screenshots. So the arrows and text pointing things out look the same everywhere.
I can help with the guide though much of the understanding about Zynthian sits in the heads of yourself and @riban. When I had a go at cleaning up the V4 and sequencer pages on the wiki I learned quite a bit but also felt those gaps in understanding as I went sifting through the forums looking for information (or testing with my own device to confirm something).
Most of the manuals i love use fixed layouts, that works very nicely for printing/PDF but they are difficult to implement in a mediawiki system. These manuals, specially recent ones, have been created by a team of technical content writers and graphical designers, using specialized layout software. In some cases, they are highly specialized teams.
In our case we are, mostly, engineers trying to write technical content , using a wiki system, that is a fantastic tool for collaborative documentation, but lacks layout functionality. We can improve design and look & feel, probably we can improve a lot, but we must be conscious about the tools we are using and adapt the contents to the media. This has pros and cons.
Of course, we MUST take ideas and concepts from good examples. Inspiration comes in many ways.
FYI, this is my favorite user guides at the moment:
Well you probably won’t get a TE style manual without help from a web-dev+graphic designer. Mediawiki could get some of the way there with multi-column and image arrangement layouts. With some understanding of templates it might even be made robust.
I did some searching but couldn’t find a straightforward way to implement columns aside from pasting in CSS code (test below). Unfortunately it then becomes messier to edit after it has been created. Though you could say that about any medium-large piece of content in a wiki that leverages a lot of formatting. It can be easier to just start again rather than doing more than a simple edit.
On the other side, there are plenty of options for image arrangments and they aren’t too hard to figure out.
Yes I agree, I will try to contribute during the following weeks.
Once a good enough User Guide is achieved, it will be possible to import it in other tool like mkDocs or Sphinx (maybe with a Pandoc pass to convert Wiki syntax in markdown or reStructuredText) to create nice looking static html pages and pdf documents.
Zynthian built in webserver should (like in a RFC ) embed this html documentation.
Now it works in mobile, including the topbar version selector.
The first sections have been improved a lot, including a features and details not documented until now. If you are using Oram, you should read it ASAP!!
We have defined a set of icons and some formats for generating per-view ui-action tables that are quite comfortable to read and easy to understand, i hope. We have V5 & V4 versions, like this:
For sight impaired people we are adding alternate texts with the table info.
I spent a ton of time to prepare mockup templates that allow generating these images in a reasonable time, so i expect to advance faster in the next days/weeks.
