updated diagram logos

[mulyaj]

Have a look at the updated pics - the positioning might be a bit off since I didn't have the source file

[ann0see]

Hi mulyaj, Thanks! I'd use the server icon for the servers and maybe change the color of the arrows.
But all in all, I think it looks good.

[mulyaj]

Ok, I'll look to change that

[ann0see]

BTW, I'll look for the source files.

[ann0see]

Ok. I think they are here: jamulussoftware/jamulus#64 (comment)

[mulyaj]

Ok, here are the updated pictures.

[ann0see]

Great! Thank you very much!

[gene96817]

Very nice.
I know you can't cover very variation.
In my case, I have both server and client on my LAN but they are separate machines.
For me, the point is a server can be out on the Internet or on the private LAN. It is incidental that both server and client is on the same hardware.
In the diagram, it implies, unless you are on the jam session, your bandmates don't have a session. In my case, the server is always availble (to the public) and a server on the LAN is very much equal to servers on the public Internet. The use of my notebook and the client is completely independent of the server on my LAN.

I am ok if we decide my configuration is a special case. I do think it is important to point out a public server can exist on a private LAN.

Thanks for your work.

[pljones]

In my case, I have both server and client on my LAN but they are separate machines.

Same here.

I'd also lose the grey "cloud" behind the server logo when it's "your computer". Generally, your own computer isn't a cloud instance...

So I'd show three examples:

• remotely hosted server, not on any of the performer's own networks ("cloud" background to server icon)
• LAN hosted server, but separate to any of the performers (just the server icon)
• Single machine running server and client, with other performers connecting (both icons shown on the one machine)

[gene96817]

@pljones Sometimes I feel there is so much discussion about running both client and server in a user's machine that this scares off new users. New users just want an easy to install app. Adding the server to the picture is a much higher level of (potential) complexity. Then discussion of command lines is the proof Jamulus is not a simple app. I just want to offer this as a reminder to our development team about the documentation seen by the general user.

[mulyaj]

Would it be ok to keep the diagrams the same for now?

This PR is just to keep the logos up to date.

[pljones]

@pljones Sometimes I feel there is so much discussion about running both client and server in a user's machine that this scares off new users. New users just want an easy to install app. Adding the server to the picture is a much higher level of (potential) complexity. Then discussion of command lines is the proof Jamulus is not a simple app. I just want to offer this as a reminder to our development team about the documentation seen by the general user.

In that case, keep it to the standard "client connects to public server using directories for lookup" and leave everything else for more detailed documentation?

[gilgongo]

@gene96817

I just want to offer this as a reminder to our development team about the documentation seen by the general user.

As the original creator of these diagrams, I'd say that with hindsight their production was a mistake. We're never going to agree who they are for or what level of detail they should have. The fact that "main stream" software like Zoom or Google Drive don't present diagrams to their users should be a clue that they aren't a desire of normal people when using software.

[gene96817]

@gilgongo The diagrams are quite good. I was commenting on a detail. I'll bet that when you created the diagrams, you didn't expect the explosion of users. I think our documentation need to be considered in three tiers: the app user (I just want the app to work), the advanced user (technical but not a programmer; "I don't read code"), and the developer.

[gilgongo]

@gene96817 :-) I did in fact create them for general users when we first expanded the documentation in response to the interest from Covid last year. More fool me!

As to the idea of "tiers", that too is far from simple for similar reasons to diagramming, in fact. At least, if you mean literally arrange our documentation around those notional users, then that would invite endless debate about what a "technical" user or a "developer" is, level of detail, assumed knowledge, etc. and we would never agree. I don't think there are any examples of websites for similar software arranged in that way either. Instead we aspire to the inverted pyramid approach.

[gene96817]

@gilgongo I agree documentation is hard. You can't succeed in creating documentation where each reader feels it is perfect. Documentation is an expensive process that most commercial projects have eliminated.

In the ancient days of computing, documentation was created in a structured way with "volumes" from user manuals, to theory of operations, to admistrator, to internals. For a few projects, I used the diagrams as the bridges between the tiers; they were used to be visual clues connecting the tiers.

Anyway I agree documentation is inconvenient and hard to get right,.

[gilgongo]

Anyone know what to do about the conflicts?

[hoffie]

The conflicts come from the PNG optimization in #356.

Solving the conflicts should be done by overwriting the existing (PNG-optimized) files by the version in this PR. This drops the PNG optimization for the affected (3?) files, so this would have to be repeated.

Doing it the other way round does not make sense, IMO.

Side note: As neither #356 nor this change touch things which must be translated (right?), it might have been better if they went directly to release? If there is agreement, we could still cherry-pick #356 into release and merge this PR to master.

Edit: I just noticed that this was already discussed (but maybe before the release was tagged?).

[mulyaj]

closing this PR via #381