Documentation Map

From Audacity Wiki
Jump to: navigation, search
This is a map of the various pieces of Audacity documentation we have. It is written for people who may want to help us write documentation, rather than for people looking for information

The Manual

The Manual is our main user documentation.

The manual is written and maintained on a wiki.

  • It is primarily a reference that aims to cover every menu item, every toolbar button and dialog.
  • It has a small amount of tutorial content too.

We found that there are so many possible workflows and uses for a sound editor that having comprehensive tutorial content isn't possible. Should we have a tutorial on recording bats? With tutorial content it is very hard to set limits to the scope of the manual. A lot needs to be written that is beyond Audacity itself. It is hard to control quality when you don't control scope.

Limiting the scope of the manual to being primarily a reference means we can do a better job of what we do commit to document. We do have tutorial content. The pattern is that tutorial content is generally developed first on this wiki. When it is 'good enough', and provided it is not too niche, it is then transferred to the manual.

We have plans for making some extracts from the manual into pdf documents, and possibly offering translations into some languages - see the name checked sections below.
As well as the wiki, we have a somewhat experimental interactive version of the manual called 'What is That?'. It was inspired by the clickable hyperlinked image of Audacity on the Audacity manual front page. It is essentially the same as the manual, just with a lot of javascript programming for the images. One plan (of many) is to use some coding tricks to incorporate the interactive diagrams into the standard manual, when it is read online.

Tour Guide (in the Manual)

The manual has a tour guide of features in Audacity. The tour guide does not tell you how to use the features. It would be too long if it did. Instead it links to the relevant reference sections. The purpose of the tour guide is to quickly give a new user an idea of the range of features available in Audacity.

New Features Guide (in the Manual)

This provides an overview of new and changed features in the most recent release. We have this in the manual, and we also archive a copy for each release in this wiki.

FAQ (in the Manual)

The FAQ is user facing documentation for the most frequently asked question. It is designed to save our support staff time. The idea is that we can point users at the relevant FAQ entry.

Tools for working on the Manual

The manual is produced in wiki and uses wiki templates. Some large tables in the manual, such as lists of all commands, and many of the images in the manual, notably the screenshots of menus, are produced using tools. See Magicke Spells for a headfirst dive into those tools. One significant tool for working on the manual is WIT


Website

Our website is mainly for getting people to our downloads.

We don't expect long linger times on our main website. It is mainly about getting people to our downloads. It also gets people to general information about licensing, and it says a bit about what Audacity is.

Documentation in GitHub

Most of the text (or markdown) documentation files we provide at GitHub are the standard kinds of files provided in source code distributions.
Usually we link to greater detail in this wiki. We should also consider the meta data at GitHub such as the labels and milestones text as part of our documentation as to 'how things are done' around here.

README.txt

Starts with links, then provides brief license info, copyright, brief recent changes information. A fuller log of past changes is in CHANGELOG.txt. There is too much there for it to be part of the README. A fuller license is in LICENSE.txt

INSTALL

INSTALL just directs people to the relevant build files.

build.txt

We have separate build.txt for:

We deliberately only document one way to build Audacity, leaving variations and elaborations to this wiki, and we reference the wiki from that document. Why? A snapshot or tarball captured from the Git Repo will not contain the most up to date information on building. We can provide more timely information in wiki. We do not want to have to re-release a particular version of Audacity simply to update the build instructions for some variant of linux.

CONTRIBUTING.md

'Contributing' links to Contribute which is a better landing page.

CODE_OF_CONDUCT.md

We've had some discussion about how easy it is for miscommunication of 'tone' with text as the medium. We want to say something about that in there, but no one has been brave enough to propose wording. This document is mostly about what to avoid, and as a group we want to put more energy into actually being a welcoming community - e.g responding well to pull requests. So there is less energy for writing rules about how to behave than for getting on with day to day collaborative development - with all the mismatches of expectations and communications that can happen with that.


Documentation for Contributors

We provide these pictorial links (below) on the front page of this wiki. These are to 'portals' for potential contributors. We need to make sure that these lead to content that is useful for these categories of contributor.


For Developers

We have:

Feedback

User support / Documentation Writers