Difference between revisions of "Documentation Map"
Revision as of 21:41, 16 October 2018
|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 Documentation in GitHub
- 3 Documentation for Contributors
The manual is produced on a wiki, at https://alphamanual.audacityteam.org/man/Main_Page. 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? YES we should. But we don't. 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 have plans for making some extracts from the manual into pdf documents, and possibly offering translations into some languages|
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
Documentation in GitHub
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
We have separate Build.txt for windows, mac, linux. 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.
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