Difference between revisions of "Documentation Map"

From Audacity Wiki
Jump to: navigation, search
(new page.)
(No difference)

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

The Manual

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.

Bulb icon 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

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

Build.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.

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

For Developers

We have:


Feedback

User support