Writing Tutorials and User Guides

Audacity welcomes contributions to both and , whether it's a small spelling correction or an entirely new guide. If you're not sure what to start with, check out some good first issues:

Gitbook works a bit like a wiki in that you can edit all pages freely, but unlike a wiki, it uses git's "everyone has their own branch" principle. That is to say that the changes you make are independent of everyone else's changes, and won't show up on the main (live) website until the branches are merged.

To some degree, this means that you can do whatever you want in your branch. That said, there's some things which make things easier for everyone involved:

When editing on Gitbook, you can edit existing pages, but you cannot create new ones. If you'd like to make a page about a new topic, write to LWinterberg in the . You also can hand in Markdown files or Word documents to him directly to add. This restriction does not apply when , however, there are other when editing through GitHub.

Making Video Tutorials

Video tutorials are highly appreciated as part of a guide. You can upload them to YouTube (or Vimeo/Dailymotion/...) and embed them in your guides, or in other people's guides, like this:

We have some requirements for which video tutorials are accepted into Audacity Support pages (see the for more info)

Any page of both support.audacityteam.org and plugins.audacityteam.org can be edited either on Gitbook (see Writing Tutorials and User Guides for instructions) or using Markdown syntax on GitHub.

Editing through Github.com

A link for GitHub is shown either on the right-hand side or in an overflow menu of any page:

Once you are on GitHub, you will see a pencil in the top right of the file.

You now can make your changes to the page.

Once you are done, press Propose Changes

This brings you to a page where you can review your changes. If you are satisfied, click Create Pull Request.

After you click "create pull request", it will show up on and await review by an Audacity team member.

Editing through a local editor

You can edit Markdown in any text editor. More advanced editors like may show useful shortcuts and visualizations for easier and faster editing, but in principle, even the simplest text editors like Windows Notepad can be used to create them.

To get started, first clone the repository, either using git clone by clicking the code button on and opening it in GitHub Desktop

Once it's cloned, you'll find the files of support.audacityteam.org in the main branch, and the files of plugins.audacityteam.org in the plugins branch. Any additional branches have been split off from the main branch to preserve documentation for previous versions of Audacity.

Technical notes

Outside from the , there are some more technical things you need to be aware of:

• The sidebar menu is handled through , not the file structure itself. If you want the page you created to show up in the sidebar, you will need to update this file accordingly. That said: Try to match the structure of SUMMARY.md with the folder structure.

• While you technically can work directly in your fork's main/plugins branch, it is highly recommended to make a new branch based on upstream/main or upstream/plugins instead for your changes. This way, you can always fast-forward merge the latest changes into your fork.

General

The goal of the user guide is to provide explanations on how to perform various tasks in Audacity.

Features vs tasks

Documenting features seems like the obvious thing to do: Audacity has various menus, so better have a list of what every option in that menu does. However, this leads to the situation where some pages are completely unfindable as a reader already needs to know where certain options are in the menu in order to find out what the page would be called. For example, the feature containing the slider for the recording and playback volumes is called Mixer Toolbar. But nobody except the people most intimately familiar with Audacity know it's called that!

To combat this, try to write your guides as a way towards a goal, or a task. The above example, instead of naming the page after the feature, name it after the task it does, so:

Tasks aren't necessarily tied to individual features. For example, can talk about several tools as once as they all are means towards a common goal.

If a feature has many different modes or options that are unrelated to the task you're describing, avoid making long lists of what all the feature can do. Focus on the task-related ones instead.

If a feature has several ways to access it, use the most accessible option. For example, for an "how to play audio" article, simply mention the big green play button and the shortcut Space. Don't also mention Transport > Playing > Play/Stop.

There are some exceptions to this, especially when documenting more "advanced" features like Macros which need extensive guiding about how to operate it. Instead of a linear "go here, then here and there, and then you're done", split them up into sub-tasks (for macros: creating macros, editing macros, etc.) and keep these unrelated tasks on one page. Avoid breaking it down to the point where you are explaining individual buttons (don't say "the cancel button cancels the effect without applying it")

Target audience

Audacity's user base consists largely of casual users. As such, you can't expect the readers of your guide to understand even fairly common audio terms (for example: compressor or loudness vs volume), unless it's directly connected to the topic you're writing about.

For example, if you write a guide about compressing and expanding audio, you don't need to hold yourself up on explaining what a compressor is, since the only people who'll ever end up reading that guide are people who already know about that. However, if you were to mention a compressor on a page about general audio editing, you would need to explain what a compressor is good for.

That said: If it's possible to describe a feature without needing to resort to lingo, use it even if it's slightly less accurate. For example, "punch-in repair" would be the accurate term for , but also is way harder to understand and thus to find.

Scope

While there's a lot of things you can write about in relation to Audacity, keep in mind that this site is focused on user guides (or how-to guides, or tutorials - they all have the same idea). We want to minimize work on contributors while maximizing impact, so guides should be kept as general as possible. Only use qualifiers such as "for podcasters" or "for musicians" if their use case shares almost no resemblance to what everyone else would be doing anyway.

Writing style

You can address the reader directly ("you"). You should remain impartial in the process though, so no "I" or "my".

The overall tone should be friendly but not patronizing, and the language should have a healthy middleground between casual and technical.

Page titles

Titles should reflect the task you're trying to teach. For example, if you're teaching how to add reverb, the title should be "Adding reverb"

The title should be concise (try keeping it below 60 characters).

Page titles should be written in sentence case. So generally, the first is capitalized while everything else is not, except proper nouns and acronyms ("Audacity", "FFMPEG").

Introductions

Underneath the title is a field for page descriptions. These descriptions are the first thing users see of the article when looking at Google, or seeing an embed to it somewhere.

As such, they should give a good summary of what the page is going to be: In a few words, how will a goal be achieved? What features will be used?

Instructions

Instructions should be written in a step-by-step list where useful. For example:

1. Do This

2. then that

3. then a third thing

If you need to interrupt the steps for explanations, you can either do

1. Do this

2. then that (shift+enter) Note: This is an explanation on a new line

3. then a third thing

Instructions for different Operating Systems

If instructions are different depending on the operating system or other factors, you can use tabs, like this:

Tabs aren't part of standard Markdown, so they probably won't show up properly if you're using github or a local editor. They'll show up just fine on Gitbook though.

Technical explanations, asides, and manual backups

If a task has a main way of working, but may benefit from additional context, you can use the Expandable block:

Images

You can take screenshots using the clipping tool or tools like ShareX. ShareX has the advantage that it has built-in tools like arrows, step-by-step bubbles and labels which can help you visualize several steps at once.

With images, there always is a tradeoff between easy maintainability, clarity and context. So crop them as much as possible without losing important context, and use them in a way that makes updating them as painless as possible.

Info boxes

Gitbook offers 4 types of info boxes.

These info boxes aren't part of standard markdown, so if you're not using gitbook itself, but edit through Github or a local editor, they will look a bit silly in your preview (but show up correctly here).

Video Tutorials

If an image is worth a thousand words, a video tutorial can be worth a million: At it's best, it can tell the entire story the written guide would make in a way that always has all necessary context and requires no lengthy description of where to find things.

However, video tutorials can go out-of-date incredibly quickly and then cause a lot of confusion among viewers.

Because of this, a video tutorial must follow these rules to be added to an Audacity Support page:

• The video must clearly state what version of Audacity it's referring to in the beginning.

• The video must be in the language of the Audacity Support page it's meant to be embedded in. Right now, that's English only.

• The video must be a dedicated Audacity tutorial or how-to guide.

• The video must refer to Audacity Support as the place to get up-to-date help from.

Best Practices for Videos

The following points are considered best practice for video tutorials:

• Start with the purpose and version number and then go straight into the content: "To do XYZ in Audacity 4.2.0, first go to..."

• Use a script which you follow when making your video. This will automatically eliminate the following two points, and also get you a long way towards making subtitles.

• Avoid going off-topic, eg "hey guys, and welcome back to another video! my sister's aunt's nephew requested I make a tutorial so he can cook his eggs using Audacity to which I said..."

About this document

This is a living document. It contains the best practices, as determined by the community. Feel free to discuss additions and changes on the discussions page, or in the discord.

TODO

Pages under this section are just stubs. Feel free to work on them. Check out the and for more info

From

(this probably is a category on its own, but let's write it on this page for now)

• Making new tracks

• Use case: spoken word with music in the background

• Mute & Solo

• Moving clips & Sync lock

• Splitting a recording into several tracks

• Synchronizing with claps

Contrast this page to:

• raw markdown: https://raw.githubusercontent.com/audacity/audacity-support/main/community/contributing/tutorials/gitbook-markdown-syntax.md

• Github's markdown renderer: https://github.com/audacity/audacity-support/blob/main/community/contributing/tutorials/gitbook-markdown-syntax.md

• the live page: https://support.audacityteam.org/community/contributing/tutorials/gitbook-markdown-syntax

Heading 1

(shows up in the outline)

Heading 2

(also shows up in the outline)

Heading 3

(does not show up in the outline)

Headings can be used anywhere, including inside other blocks.

Inline text formatting options

Bold, Italics, Code, Strikethrough, , , , page link: , page anchor link: , colored text, colored background, both colored, LaTeX:

These can be used anywhere.

Lists

• Unordered

• List

1. Ordered

2. List

• Task

• List

• List with

  1. sub-items

  2. can have

Lists can be used anywhere, including inside other blocks. They can only include inline content and other (nested) lists.

Infoboxes, quotes and code blocks

Infoboxes:

A quote block

These blocks can be used inside of Tabs. The code block can also be used in Expandables, but cannot have other blocks inside it. The quote block and infobox can have headings, inline content and lists inside it.

Images and files

Inline image:

Image block:

Attached file:

Embeds

Embeds cannot be used inside of other blocks except the Tabs block, nor can other blocks be placed inside them.

Tables

Tables cannot be used inside other blocks except the Tabs block, nor can other blocks be placed inside them. Inline content works inside of text columns only.

Cards

Cards and tables can be converted into each other.

Tabs

Tabs cannot be used inside other blocks. Tabs can have most other blocks inside them, except of other tabs, expandables, and API blocks.

Expandable (Details block)

Expandables cannot be inside other blocks. Expandables can have headings, lists, code blocks, and inline content inside them.

Drawings

A Gitbook-specific drawing thing, generating SVGs. Likely useless when using Markdown.

LaTeX

Cannot be placed inside of other blocks except the Tabs block. That said, an inline variant is available which can go pretty much anywhere.

Web API methods

API title

GET https://example.com/example

shows itself up in the outline. Example of all available parameters follows:

Path Parameters

Query Parameters

Headers

Cookies

Request Body

Cannot be used inside other blocks. Can only contain plain text. Unfortunately very tailored towards web APIs only.

Dividers

The above line is a divider.

What are the main uses for Macros?

Macros in Audacity can be used for:

• Batch processing: Apply one or more effects to multiple audio files and export the processed audio into a new file.

  To use this select the Apply Macro to: Files... button in the or the dialog.

  For more detail on batch processing please see .

• Effects automation: where the in the or tracks in the current project is subjected to the same prescribed sequence of effects, and optionally, a file exported from the entire audio.

• Effect presets: where selected, commonly used, effects are stored with your preferred settings for quick re-use.

How to access Macros

You can manage and apply Macros using the :

• Tools > Macros... to manage Macros: them

• Tools > Apply Macro > Palette... for a

• Tools > Apply Macro > named Macro to

There are some and tips on using them.

Use Tools > Macros... if you need to create a new Macro or to edit an existing Macro.

dialog

Use the Shrink button to show a reduced dialog which lists the existing Macros.

This dialog is also available directly via Tools > Apply Macro > Palette...

Apply Macro to

Both the dialog and the dialog have Apply Macro to buttons:

• Project applies the selected Macro to the current project.

• Files... applies the selected Macro to selected external audio files that are in a single directory.

For more details see the page.

Macro Command Parameters

Commands that call Effects, Generators, Analyzers or Tools, use the same familiar graphical interface (GUI) as appears when they are used from the normal top level menus.

Many of the other commands provide a simple GUI comprised of checkboxes and text entry boxes. Typical examples can be seen in the and menus.

Please see for more details.

Sharing a Macro

You can export a Macro as a TXT file using the Export button in and send it to another user, or copy it to another computer for use there

You can import another user's Macro, or a copied macro of your own, into your Macros folder by using the Import button in .

Where Macros are stored

Each Macro is automatically saved as a separate text file with TXT in the Macros folder in Audacity's folder for application data:

• Windows: Users\<username>\AppData\Roaming\audacity\Macros

• Mac: ~/Library/Application Support/audacity/Macros

• Linux: ~/.audacity-data/Macros

Macros Examples

See the page for examples of using Macros

Audacity can record and playback audio on your Windows PC using one of the following three alternative interfaces:

• MME

• Windows DirectSound

• Windows WASAPI

ASIO (Audio Stream Input / Output) is an additional proprietary interface to record and playback audio in Microsoft Windows. ASIO bypasses the Windows audio mixing components to provide lower latency direct communication between computer audio software and hardware. Most audio recording interfaces manufacturers provide a driver to support ASIO.

• ASIO supports 24-bit sampling which is only otherwise available using or WDM-KS (Windows Driver Model Kernel Streaming). 24-bit sampling allows greater dynamic range, lower theoretical and greater resolution at lower audible volumes.

• An unmixed ASIO output is "bit identical" to the original source.

• Multiple physical input and output channels of the hardware are accessed over one single device.

Windows interface protocol support multi-channel recording on some sound devices, but not the very low latencies that are possible on ASIO.