Documentation: Change the user’s guide structure and style

The zynthian documentation is primarily here…

ZynthianWiki in a MediaWiki world.

It’s better than some, but not as good as others and for a project like this a very important tool for users, developers, browsers, browsers, API users, passing ravens with a grudge, and the last thing handed to miscreant zynthers before they are tossed off the battlements during on of the less frequent purges we have around here.

So as the zynth and the community have changed over time the documentations deserves review and what better time than as we approach a new stable…

So any comments, observations, criticisms, praise, contributions, offers of help or dastardly attempts to overthrow the benevolent dictator or his hideous sidekick will now be appreciated…

I will now adjourn to the parts of Wyleu Towers with by far the best view of the fearfully threatening world onthe other side of our hallowed valley and wait to see who turns up and suggest an effective mechanism for them to return to ground level in as an efficient way as possible. . . .

The could well be rook soup as well .

Please! any thoughts…


I created a copy of the current wiki user guide here. It was updated for the 2210 staging although that was a while back so it may not be completely up to date.

I think this is a technical guide, describing what the functions are and how to use them. I suggest a more tutorial based guide which takes the user through the process of using Zynthian, introducing terminology, features and workflows as it progresses. It could have indication of key terminology and features, e.g. using breakout boxes so that a user could find the technical description within the guide. The step sequencer guide is written in a tutorial style which may give an idea of what I mean.

I feel that users would benefit from being taken through how to use the device in this way rather than just told what the features are, what they are called and how each works. The former may give an easier introduction whereas the latter can be an initial barrier. We must however retain the reference of features for experienced users to refer back to. I think this can be done within a single guide, not two separate documents (which reduces support overhead).


I agree @riban’s view and would propose to start writing the root index. I mean, the first-level list of subjects or root structure.
Also, we should have a kind of “style guide” with some examples, so the new user’s guide have a coherent and fancy look & feel.
I suppose everybody agree on using the wiki for this.


Do we necessarily have one overarching style…? .
I certainly think there should be a style guide but I would see these as contextual mechanism that allows description of core concepts from different standpoints

Perhaps a parallel comment section where a developer and a musician could address each identified concept from their own unique standpoints. ?

That would require first a list of concepts.
The construction and ordering of that list would be good to unify.

There are just under 100 pages in the current wiki as listed List of current wiki pages

I would be interested to know if the musician and the developer would order those pages in an identical fashion…

Could we make more use of the wiki namespace feature…?

And what about serving the documentation html files locally with Zynthian built in webserver ?

This could be usefull when playing without any network connection (except Zynthian Access point)

Seems sensible and useful in exactly the situation you describe.

“Perhaps a parallel comment section where a developer and a musician could address each identified concept from their own unique standpoints. ?”

I like this idea very much. With the huge upgrade coming soon, a lot of new wiki pages will need to be written. Sometimes technology gets in the way of creativity. Sometimes things that are instinctual to a developer can be incomprehensible to a musician, and vice versa.

I’m looking forward to using the new audio recording software. Perhaps we can teach a grumpy raven to play a carillon?

Would that be like a carrion crow?

I have to constantly remind them that I’m not dead yet.

Looks quite good…