Documentation suggestions

Audacity Help Forum GNU/Linux
1

Hello,

1. In ALSA Latency - #4 by Gale_Andrews Gale Andrews wrote:

The Manual for the next release of Audacity will make very clear that the “Audio to buffer” setting also affects playback.

Could this fact about the “Audio to buffer” setting be added to the FAQ Audacity Manual, in the Playback section? Maybe something like:

_Q: Why do very short audio selections (less than 1 second) not play at all, or only a tiny bit of the end of them plays?

A: In Recording Preferences Audacity Manual, try setting “Audio to buffer” to a lower value. This setting affects playback as well as recording. Values as low as 5 ms may work well on newer computers._

It took me a fair amount of searching to find this answer. I almost submitted a forum request about the issue. I was trying to play an approx. 140ms “beep” sound with “Audio to buffer” set to the default of 100 ms.

Also, I don’t find anything about this setting in the current alpha (2.1.0) manual http://manual.audacityteam.org/man/Recording_Preferences. Maybe the playback effect of the “Audio to buffer” setting should be mentioned there too.


2. How to switch from waveform to spectrogram display doesn’t seem to be indicated on http://manual.audacityteam.org/man/Spectrogram_View. I think the text, near the beginning of the page, that says “Here is the same recording in spectrogram view:” should have this how-to added, maybe like “Here is the same recording with Spectrogram view selected from the http://manual.audacityteam.org/man/Audio_Track_Dropdown_Menu Audio Track Dropdown Menu:”


3. Suggestion: Add an “audacity-doc” package, which contains the manual (Audacity Manual), to the daily-build PPA Audacity Daily Build : “Audacity Team” team. It’s very common for Linux software to have a “-doc” documentation package in addition to the package for the executable. I think that having the manual distributed in this format would be much more convenient for users and would prevent issues like the one in Manual not found in Audacity 2.0 - #3 by edgar-rft

The manual would come from http://manual.audacityteam.org/man/Main_Page since that is the manual version that corresponds to the daily (alpha) PPA build.


4. Maybe the manuals (production version & alpha version) should have the applicable software version number stated on every page (preferably by means of scripting), and/or the URLs should be changed to indicate which manual they are part of. Currently, the main page for the production manual is:
Audacity Manual
And the main page for the alpha manual is:
http://manual.audacityteam.org/man/Main_Page
And there is nothing in either of those URLs to distinguish which manual it is.

Currently, a user could have a printout or locally saved copy of a manual topic, or have been given a URL to one of the individual topic pages, & not be able to tell what software version it is for. Not all printouts or locally saved copies will include the URL, so I think there is some value in including the version number in the text of the page.


5. Suggestion: Make the alpha manual easier to find …

a. … on the website. Currently, if someone navigates to http://audacityteam.org/ and clicks Online Manual, they get the manual of the production Audacity version Audacity Manual. From there, they have to guess that they should click Wiki (which, until the user mouses over it to find out the URL, might be assumed to be a link to the current page, since the production manual may be recognized by the user as being a wiki) and only there (Missing features - Audacity Support) is the alpha manual listed.

A solution might be to add to Audacity Manual a box, similar to the one on http://manual.audacityteam.org/man/Main_Page that starts “This online Manual is only for …,” directing alpha users to http://manual.audacityteam.org/man/Main_Page.

b. … in the alpha version of Audacity. That is, have the “view the content online” link in Help > Manual point to the alpha manual rather than to the production manual.


6. The closest thing that “Help > About Audacity…” has to a build ID is a build date at the bottom of the Build Information tab. Maybe a date, as opposed to a revision-control commit ID, is OK since perhaps your team members only need to know whether a user has the current version, but at least the build date could possibly be put at the top of that tab (and preferably right under the version number at the top of the Audacity tab) so users can easily find this info for support requests?

For instance, a user could be running the daily PPA version (since multiple 3rd-party blogs point users to this), but have turned off that PPA in their APT client (Synaptic or other) because they don’t like being prompted frequently to download an updated revision. Then maybe the user forgets that it’s been turned off, and subsequently they ask for support on the forum. There are other similar scenarios as well. The obvious version number (currently 2.1.0) wouldn’t be enough to tell support staff that the user doesn’t have the latest revision. Having the build date or ID be prominent would assist with this.

\

In some of the above suggestions, I have used the URLs for the production (currently 2.0.6) and alpha (2.1.0) manuals sort of interchangeably. I realize that where I have suggested that a change be made to one version of the manual, maybe the team will want to change the other version.

Thanks for your attention.

2

It’s not quite so straightforward.
For example, if you use Jack Audio System, then very short selections of audio (as short as 1 sample) will play. The “Audio to buffer” settings have no effect when using Jack, so the example answer is incorrect and misleading in that case. By the time that the answer has been expanded to cover multiple possibilities (including ALSA, Jack, OSS, OSS4, WASAPI, Direct Sound, WDM, WDM/KS, Core Audio, + older computers + other factors) it becomes very difficult to provide concise advice suitable for a FAQ.

One of the main criteria for adding a question to the FAQ is that it should be a question that is frequently asked.
Although the question of playing very short sounds does come up from time to time, it is by no means one of the most frequently asked questions.

Ideally I would like there to be many more answers in the FAQ’s, but there is a problem - the longer the list of FAQ’s, the less people bother to read them.

3

True, but it is mentioned at the top of the main “Audio Tracks” page: http://manual.audacityteam.org/man/Audio_Tracks

There is quite a lot of cross-referencing within the manual, but it is difficult to cross-reference everything. There would be some validity to saying that, as the images on the “Spectrogram View” page show the track information box, and the track Pan / Gain sliders, they should also be cross-referenced on that page. Or that it should be cross-referenced to the Plot Spectrum page (which is clearly a closely related topic), or to a page that explains FFT, or to …
The underlying problem here is that just about everything is related in some way to just about everything else (Six degrees of separation - Wikipedia)

4

You would need to raise that with the PPA maintainer (Benjamin Drung Members : “Audacity Team” team)

If you don’t have the manual installed locally, all builds should display a screen similar to this when you select “Manual” in the Help menu:
window-Help on the Internet-000.png

5

Alpha versions are not intended for end users. They are (by definition) development versions. Unless a user is involved in testing and/or developing, it is highly recommended that they use the release version of both the application and the manual. Unfortunately, the rather too common use of PPA’s somewhat undermines that distinction.

Ditto.

We are always very pleased when people show interest in contributing in any way - whether it be code contributions, help with documentation, donations, helping other users on this forum, or whatever (and although my replies in this forum thread may appear to be mostly negative, the time and effort that you have made in making these suggestions is genuinely appreciated).

6

This again is not quite so straightforward.
The PPA builds on Audacity Daily Build : “Audacity Team” team have been modified by the Ubuntu packaging team specifically for Ubuntu. Many of the recent bug reports that we have received about PPA builds are not reproducible when the official Audacity source code is built according to the official build instructions, but are due to the PPA version being built using a later version of WxWidgets than the officially supported version.

When building Audacity from the source code, it is a very simple matter to include whatever information you want in the “About Audacity” screen. When using a version that has been built by someone else, you will get whatever information they decide to put there.

On this forum, we request that users include:
“which version of Linux you are using, the exact three-section version of Audacity from Help > About Audacity and whether you installed your distribution’s version of Audacity or compiled from source code.”
(pink panel near the top of each page).
We could perhaps add to that something like “or whether installed from a PPA”, though that may cause confusion for users that don’t know what a PPA is.

7

I’ve had a look to see what links to that page (how someone would get to that page), and I agree that it is quite easy to arrive there without knowing how to access the Spectrogram track views.
Yes, I agree that it would be useful to have a note / link near the top of that page to indicate how to access the Spectrogram views.
At the moment we are in “freeze” (pending the release of Audacity 2.1) so it is too late to change that for the 2.1 manual, but I will make a note to add something for the next version.

8

Thanks for all the suggestions, dg1727. :slight_smile:

I also agree that’s an omission. So we don’t forget, I added an “ednote” to address that after 2.1.0 is released. That note will not appear to anyone dumping the Manual.


Gale

9

I tweaked it to say “whether you installed your distribution’s release or daily version of Audacity”.

Gale

10

As Steve said that is a question for Benjamin, but there is nothing to stop you dumping the latest alpha Manual yourself using the wiki2htm.sh script at scriptsmw2html_audacity in the Audacity source code.

I also agree with Steve’s caution about using unofficial builds of Audacity that use versions of wxWidgets that we don’t yet support.

We could include the released (o/man) Manual with the source tarball for each release, but again Linux distributions are under no obligation to build it in.

Normally, the page titles (which not all browsers show these days) of the alpha Manual say “Audacity Development Manual”. But since the released Manual is produced by dumping the development Manual, when we are in a release process as now, the alpha Manual page titles go back to say “Audacity Manual”.

Really we should have each Manual on separate subdomains of audacityteam.org which we will probably do at some stage.

I disagree. We have to think of Windows (our largest user base) where most users definitely do not want the confusion of finding the alpha Manual.


Gale