KXStudio documentation (preparations)

[steevc]

My suggestions:

This tool can be ran by itself using 'cadence_logs' or built-in Catia and Claudia in their 'Tools' menu.

This tool can be executed as 'cadence_logs' or within Catia and Claudia from their 'Tools' menu.

Each tab shows it's own respective log. If a log does not exist, its tab will not be shown.

Note "it's" is a tricky one. Should be "its" unless shortening "it is". So both should be "its"

The 'Close' button will, as obvious, close the tool window.

The 'Close' button will, obviously, close the tool window.

view the audio-related logs and allow to copy&paste from it

view the audio-related logs and allow you to copy & paste from them

[steevc]

thanks steevc! I've updated the page according to your suggestions.
I want to discuss them just a bit to make sure I won't write down mistakes again.

This tool can be ran by itself using 'cadence_logs' or built-in Catia and Claudia in their 'Tools' menu.

This tool can be executed as 'cadence_logs' or within Catia and Claudia from their 'Tools' menu.

Shouldn't it be theirs?

Not theirs, possibly change menu to plural to.

view the audio-related logs and allow to copy&paste from it

view the audio-related logs and allow you to copy & paste from them

Using 'you' here makes it sound personal, when the intention is to have like:

Code: Select all

view the audio-related logs and allow [everyone] to copy & paste from them

Isn't it assumed that without the "you", 'everyone' is the subject?

You could miss out you/everyone, but should then omit the to as well.

I am a native English speaker and try to use proper grammar when writing, but I'm don't consider myself an expert (even though I have read Eats, Shoots and Leaves) and I'm sure I make mistakes. I know a bit of German, but wouldn't consider myself competent to write articles in it, so I am impressed with how well you do.

Is it worth making the documentation some sort of wiki so that others can help with the editing as well as adding extra information? It would take some load from you. You might have to restrict access given how keen the spammers are to reach the Linux audio scene

[looplog]

Each tab shows its own respective log. If a log does not exist, its tab will not be shown.

Ok, I may seem overly picky on this one.

There is nothing wrong with the English by any measure. I have more of a question of technical clarity.

The thing is, the log doesn't really "belong" to the tab, it is merely shown by it. The log in fact "belongs" to its respective application.

My suggestion, which you are welcome to ignore:

Each tab shows the log for the application indicated in the tab name. If a log does not exist, its tab will not be shown.

Although the difference may seem minor, my suspicion is that edits like this over the long haul will make things easier to understand.

[wolftune]

Suggestion:

"It couldn't be more simple" -> "As simple as can be"

[wolftune]

My vote for the full sentence:

"This is as simple as can be: 4 tabs for the logs and 2 buttons"

Or

"It couldn't be simpler: 4 tabs for the different logs and 2 buttons"

The main thing is just that in English we don't say "more simple" we say "simpler"
I just had the other version because that seemed better to me at first. But either of these is fine.

[GraysonPeddie]

"It couldn't be more simple than that."
"It couldn't be simpler than that."
"It couldn't be more simple than that."
"It couldn't be simpler than that."

Yeah, "more simple" is too wordy. The word "simpler" is more clear and concise.

Although I'm a native English speaker, I do tend to make mistakes.

Also, here's a tip when writing: If you use contractions such as "it's," "you're," and "they're," you will want to break them out into two words like this: "it is," "you are," and "they are."

So in your example:

Each tab shows it's own respective log.

...becomes...

Each tab shows it is own respective log.

Well, that does not make any sense. Would it?

The correct way to write is:

Each tab shows its own respective log.

What about this?

Put you're dishes in the sink.

Split up "you're:"

Put you are dishes in the sink.

Are you a "dish?" (Sense of humor intended.)

The correct way to write is:

Put your dishes in the sink.

Does that make sense?

To other native English speakers out there, is my technique effective in splitting out contractions?

[Thad E Ginathom]

A quibble on the Log app: it is not an "editor" because an editor would allow changes to be made and saved.

Glad to know the documentation project is underway!

A general hint: be as economical with words as possible. When editing, be generous with the red pen (crossing things out). This is especially true of technical writing. It is not necessary to say things like, it couldn't be simpler because that should be self evident. On the other hand, in another instance, it might be necessary to point out that simplicity (rather than doing too much) was a design priority of a program.

My prize for best technical writing goes to the original Unix team: the man pages are superb. Concentrated technical information, without a trace of the marketing angle that certain, err, windowing-software makers infuse their manuals with, and dry but not unfriendly. I started learning my computing profession with them.

[Thad E Ginathom]

I would say text window. See if other suggestions are better!

I didn't know about cadence Jack meter before, so learned something new today It is jack_meter2 on my system. Maybe because I'm looking at 11.04 still?

Note that the peak values are based on programming data...

As a novice, I don't understand what you are saying there. That might be a novice thing, but if I don't there will be others that don't.

[supercoco74]

Good! Documentation is the way to go. Sincerely, I'm still not used to all this "girl-named" tools. Documentation and set up tutorials are most needed

[wolftune]

Very minor:
"This is a very small tool with a very small purpose - to quickly view the audio-related logs"
This should be a colon ":" instead of the hyphen "-"
Where you are using hyphens, what you mean to use is an m-dash which is this: —, instead of -
You get an m-dash by pressing the compose-key and then push hyphen three times.
But in your sentence, you want a colon. The dash is used to interrupt a thought with an interjection.
The way you now have the "simpler" sentence with colon is good.

As to "logs are viewed in a text editor", how about "text box" ?

Or instead of " but here the logs are viewed in a text editor, allowing easy browsing and copy&paste"
what about "but here the interface allows easy browsing and clipboard actions"
or some variant like that?


For the other page:
"as you probably have already seen before"
remove "already" — it is redundant.

"The background color is black and gets filled according to the sound volume. Green is the low color, then yellow and finally red at the end." — I think this is too obvious. You don't need these sentences at all.

"The JACK client name used is just "M""
I suggest change to "The JACK client name is "M" for "meter"

[wolftune]

On Jacksettings page:
typo: in-dept missing "h"
add comma after "what each option does"

After the NOTE about qjackctl, maybe you should add "We recommend using only cadence and avoid or uninstall qjackctl"

[mwinthrop]

Hi - I was just reviewing the new documentation pages and would like to offer my suggestions. Please take, modify or reject them as you think best.

On http://kxstudio.sourceforge.net/_new/KX ... ations.php

It auto-connects itself to all JACK audio ports connected to the system output.

I suggest:

It automatically connects itself to all application JACK output ports that are also connected to the system output

Reasoning: Adds more clarity. I recommend spelling out "auto" as "automatically." Also, I thought the tool might connect itself between the audio tool and the system output when I read the description. When I ran the program, I saw it does not do that and thought the extra words I suggest might make this clearer.

It can configure JACK driver and engine parameters, and supports LADISH studios.

I suggest:

It can configure JACK's driver and engine parameters, and can also support LADISH studios.

Reasoning: When I read "JACK driver and engine parameters," I did not associate engine parameters with JACK, which confused me. An alternate way of saying this would be "It can configure the JACK program's driver and engine parameters," which might be clearer than my suggestion. Also, I added the words "can also" after the second "and" in the sentence, to make it follow the same verb tense as the first part of the sentence. Notice the first part of the sentence says "It can configure" and the second part could imply "It can supports," (where "It can" was stated at the begining of the sentence, which did not make sense to me).

Cadence-Logs is a small tool that shows JACK, A2J, LASH and LADISH logs simultaneously.
This is very similar to the the 'ladilog' app but here the logs are viewed in a text box, allowing easy browsing and copy&paste.

I suggest:

Cadence-Logs is a small tool that can show JACK, A2J, LASH and LADISH logs in a multi-tab window.
This is very similar to the the 'ladilog' app but here the logs are viewed in a text box, making it easy to browse and extract status messages using copy and paste commands.

Reasoning: Cadence-Logs does not show all of the logs at the same time so is not "simultaneous", but does allow the user to easily switch between each of the logs quickly using tabs. The second proposed change helps with having two "ands" in the sentence. I know you used the "&" to mean "and," but I think it would be better to spell it out and add some words so the "ands" don't get confusing.

It supports a vast number of file-types and can render in realtime and freewheel modes.

I suggest removing the "-" in "file-types." The "-" is not needed. Also, I suggest adding the word "both" after the word "render." Hence, the proposed new line is:

It supports a vast number of file types and can render both in realtime and freewheel modes.

I will try to look through your other pages tommorow and provide more suggestions.

[wolftune]

If you go with the suggestion just above of saying
"It supports a vast number of file types and can render both in realtime and freewheel modes."
Then you need to put "in" before "both" or add another "in" before "freewheel". I'd go with former, i.e. the single "in" before the both.

[Thad E Ginathom]

Great progress happening here

[Thad E Ginathom]

This is in the tradition of my beloved Unix. Having written the documentation, they then double checked with the programs, and if the two differed, they picked the best and changed the other to conform.

But your work shows itself off ...by working