|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
- 1 The Manual
- 2 Website
- 3 Documentation in GitHub
- 4 Documentation for Contributors
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.
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
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
|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.
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 just directs people to the relevant build files.
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' links to Contribute which is a better landing page.
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
- A portal For Developers
- Our Doxygen code map is based on in-code documentation which has a few 'Special topics'
- A portal for people reporting bugs and making suggestions
- A portal for User support