View source for Documentation Map

{{intro|1=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==

{{hint|1=The Manual is our main user documentation.  }}

The manual is [https://alphamanual.audacityteam.org/man/Main_Page 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.

{{intro|1=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.}}
{{intro|1=As well as the wiki, we have a somewhat experimental '''interactive version of the manual''' called [https://wit.audacityteam.org 'What is That?'].  It was inspired by the [https://alphamanual.audacityteam.org/man/Main_Page#reference 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 [https://wit.audacityteam.org WIT]


==Website==

{{hint|1=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==

{{hint|1=Most of the text (or markdown) documentation files we provide at [https://github.com/audacity/audacity GitHub] are the standard kinds of files provided in source code distributions.}}{{intro|1=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.}}

===[https://github.com/audacity/audacity/blob/master/README.txt 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

===[https://github.com/audacity/audacity/blob/master/INSTALL INSTALL]===

INSTALL just directs people to the relevant build files.

===[https://github.com/audacity/audacity/blob/master/linux/build.txt build.txt]===

We have separate build.txt for:
* [https://github.com/audacity/audacity/blob/master/win/build.txt windows]  
* [https://github.com/audacity/audacity/blob/master/mac/build.txt mac]  
* [https://github.com/audacity/audacity/blob/master/linux/build.txt 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.

===[https://github.com/audacity/audacity/blob/master/CONTRIBUTING.md CONTRIBUTING.md]===

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

===[https://github.com/audacity/audacity/blob/master/CODE_OF_CONDUCT.md 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==

{{hint|1=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.}}

{{:Category:Participation}}

===[[For Developers]]===

We have:
* A portal [[For Developers]]
** Our [https://doxy.audacityteam.com Doxygen code map] is based on in-code documentation which has a few 'Special topics'

===[[Give Feedback|Feedback]]===
* A portal for [[Give Feedback|people reporting bugs and making suggestions]]

===[[Support other Users|User support / Documentation Writers]]===
* A portal for [[Support other Users|User support]]

[[Category:Participation]]