Talk:Main Page

=Recent discussion on Front Page changes moved to Talk page=

The "Understanding Audacity" section

 * Bill 01Dec11: With recent work on the Audio Tracks and Audacity Tracks and Clips pages is occurs to me that the list of items under "Understanding Audacity" is missing a crucial "step". We lead people to understand the "Waveform", then "Audacity Selection", then "Audacity tracks and clips". It seems to me that a link to "Audio Tracks" is needed there, probably before "Waveform", even if it is a duplication of the same link in the "Reference / Project Window" section.
 * Peter 2Dec11:: I am strongly minded to agree with Bill here.  For my money it is more important to help folk find stuff in the manual (in places that are logical to them as readers) even if that involves some duplicate entries.

Smaller Details

 * James: Is it User's or Users' Manual? I.e is it a manual for one Audacity user?, or is it a manual for all Audacity users?  I feel User's looks better, but Users' is technically correct, so I would like someone to convince me that this is a manual for a user, or something like that, so we don't have to change it.
 * Peter and Gale prefer just Audacity Manual so this is agreed.
 * James: There are two note boxes, with info on translations of manual and downloading the manual. I'd like instead to put links as the last line in the 'advice box' - Audacity Manual:  (a) in other languages (b) downloadable versions.  The offline manual front page looks so much cleaner without the three boxes that I think it worth reducing the online manual to just the one.  The two note boxes would migrate to the same new page.
 * Peter 30Apr11: +1 for moving those note boxes further down the page. I seem to recall that Gale is against this as he wanted high prominence for the recruitment of translators, but I suspect that this note may not be the most effective way to recruit translators.

Warning of Version Specificity

 * Gale: 12Apr11 I think we must have the disclaimer if we are to keep this Manual up-to-date.


 * Gale: 12Apr11 Should we have a commented out intro div for 1.3.14, so at 1.3.14 release, instead of "bumping the Manual version", we uncomment the div?
 * Bill 15Apr11: Whichever is easier to do - I don't completely understand the difference, or what it would look like.
 * I had a though that we might want to flag items in the online manual that are new for 1.3.14, like this:


 * [[image:1314Flag.png]] An item or function that is new or changed in 1.3.14


 * The downside is removing all those "bug" images when it is time to release the manual.


 * James: 30Apr11 Currently the Specificity warning says:

This online manual is a work in progress. It relates to the current  development code as available in our 1.3.14 alpha Nightly Builds. Therefore the exact content of this online Manual may differ from the installed or downloaded Audacity 1.3.13 Manual or may differ from the current Audacity 1.3.13 Beta interface.

Audacity Beta is the basis for our upcoming 2.0 stable release. This Manual does not relate to 1.2.5 or 1.2.6! 


 * I'd like us to say it shorter - like so:
 * Peter 1May11: +1 for this briefer, terser text

This manual is for 1.3.14 alpha
 * This online manual relates to the current 1.3.14 alpha development code.
 * It's different to the installed or downloaded Audacity 1.3.13 manual.

This manual does not relate to Audacity 1.2.5 or Audacity 1.2.6!

Peter 1May11:A suggestion for consolidating the two "notes" at the top of the Main Page: This manual is for 1.3.14 alpha This manual does not relate to Audacity 1.2.5 or Audacity 1.2.6!
 * This online manual relates to the current 1.3.14 alpha development code.
 * It is different to the installed or downloaded Audacity 1.3.13 manual.
 * Audacity Manual in other languages.
 * Audacity Manual downloadable versions.

Gale 01May11: I would certainly like a clean up. "Different from the interface" was a one-off this time because the Manual at release had significant variances from the interface at release.

Yes I am anxious to recruit translators. Only about 1 in 12 "applicants" end up actually doing any work so we just have to keep number of "applicants" up.

I don't like the "Versions of the Manual" page very much as it seems to contain two completely different concepts. If we go with my suggestion below I think we can delete that "Versions" page.

After we made the Manual relate to 1.3.14 I have had a *lot* of e-mails asking where the 1.3.13 Manual is, and "what's the difference between the versions?", so I feel we still need to address these on the front page rather than a link.

My address on the front page serves a dual purpose in that it's the main source of feedback on the manual. I don't think that means we need my address on the front page, but we should tell users somewhere how to send feedback (preferably to feedback@). In the footer? Or a link to feedback@ and Contribute in "Index, Glossary and More"?

I'm suggesting the two divs below. Our current second one looks threadbare. If we feel my second div for languages is too much, it could be replaced by a bullet point in the single div to a page about "Other languages". We could have a "Getting Started" page for translators anyway. At the moment that help is provided by e-mail but nicely formatting a "Getting Started" page would take some time.

This online Manual is only for 1.3.14 alpha. This Manual does not relate to Audacity 1.2.5 or Audacity 1.2.6!
 * It relates to the current 1.3.14 alpha development code.
 * Use the Help menu in Audacity 1.3.13 Beta to access the installed Manual for that version.
 * You can also download and install the 1.3.13 Beta Manual for the zip version of Audacity or for Linux.

Other languages:
 * A few pages have translations to other languages. Click the country flags at the top of the page.
 * Otherwise, click here for help in other languages.
 * Translators urgently required. Please write to our feedback address if you can help.

Mostly about Tutorial Links

 * Peter 19Feb10 - updated 26Feb10 - updated 5Jan11: I would like to appeal strongly for putting links to the Tutorials onto this Front Page.  My feeling is that many users who land on the Front Page will not notice the Nav bar and will thus miss out on noticing that we have the tutorials.
 * I would propose having a whole section on the page with its own dark blue bar labelled "Tutorials" and its links in light blue boxes - just like the other sections.
 * We could then lose the Tutorials page altogether if we wanted to, but retain the "Tutorials" link in the Nav bar and instead point it to the relevant section of the Front Page - just like "Using Audacity" and "Reference". This would be more a more consistent UI.
 * The link to Tutorials in the yellow box titled "New users may want to ..." could then be removed in favour of the proper Tutorials section.
 * I note that all the other items listed in the nav bar also have an entry somewhere in the Table of Contents on the Front Page - the only exception is Tutorials.
 * The two links that are on this page give no indication to the user of what is in the Tutorials - they have to click through to the Tutorials page to find that out.
 * And note carefully that the navigation sidebar and the yellow "New Users ..." box with the links to the tutorials sidebar both disappear off-screen as soon as the reader scrolls down to the main blue section of the front page.
 * See this page for various mock-ups of a revised TOC section of the Front Page User:PeterSampson
 * Peter - Update 25Jan11: Following extensive discussions on the forum and the manual editors' email list we have worked through several versions of the mockup of these suggested changes. Version-10 of the mockup was implemented by Gale Andrews on 23Jan11.  Many thanks to Gale for his help in developing this proposal
 * The "Getting Started" and the "Tutorials" have been moved into the top block of the TOC
 * The top block has been consolidated and renamed to "Using Audacity" - containing "Understanding Audacity" and "Help with Advanced Topics" in addition to the "Getting Started" and the "Tutorials"
 * The yellow box "New users may want to look at ..." that previously contained links to the "Tutorials" page "Getting Started" etc. has been removed
 * Inconsistent uses of ellipses have been removed.
 * The bottom block of the TOC has been tidied and renamed to "Index, Glossary & More"
 * Note that this is still a "Work In Progress" and we anticipate making further modifications to the Front Page in the future.


 * Bill 05Jan11: To edit the ToC template go to this link Template:Table_of_Contents. But James notes on the Talk page that proposed new ToC layouts should first be created in the user's own space.

Balance between 'What' and 'How'
Bill 15Nov10: Posting here rather than to -quality, as my comments relate to the manual rather than the narrower discussion of what to name the panel at the left of the tracks. Those involved in the -quality discussion (sorry, I can't find the nabble archive for -quality) will recognize the context, and may wish to pull other points from that discussion.
 * Gale: Much of these and other discussions turn on how much weight to give to less savvy users' needs vis a vis "standard practice", which might dictate other solutions. Maybe I give too much weight to these sort of people, but they can be very resentful and angry about what they see as "geeky" interface and documentation that says what things are but not what they do. I think our Tutorials help here to some extent and should be further developed/extended. User feedback about calling everything "controls" in the 1.2 "track Control Panel" was hostile. I think we will have to do it if we go for "Track Control Panel", but hopefully the general care we're taking not to be geeky in this Manual will outweigh any problems.
 * Bill I think we have made great strides in moving in that direction. Of course we have to document what something "is", but I also believe we (mostly?) document what it "does". This is certainly something to keep in mind when creating/editing/proofing pages, and could possibly be added to the Consistency page. A button *is* a control, as is a drop-down menu. Get used to it. It's a computer program. Learn the lingo and you'll be better equipped to understand and interact with other computer programs. I think we may be doing a disservice to our "less savvy" users if we do not take that approach. +1 for more/better tutorials. In my experience they are much harder to write than straight documentation. There is a very fine line between "too dumb" and "too complex", between "too much" and "too little" information.


 * Some experiments:
 * Edgar's front page mock up
 * Bill's horizontal front page mock up
 * Bill's vertical front page mock up


 * To Do:
 * Quick Help, Read Me First, Audacity for the Impatient - how do they work together?
 * "Wall of links" in the Prefs section of the table

''Talk page trimmed by James, 14thDec09. If I've trimmed too much revert it, rather than argue with me.''

General Points

 * note div in place of "About this manual". "Quick Help" and "Tutorials" removed from table and moved into the note div
 * Tutorials index page resurrected
 * No "Table of Contents" header. It really isn't a table of contents
 * Horizontal Layout for front page contents with two columns is preferred to pipes in one column or vertical layout with two columns.
 * Table of Contents needs to be on the front page. We don't want readers to have to click again to get to it.  We do want a two column layout, not a one column layout 'with pipes'.
 * Family pages a good idea. Families include preferences, toolbars and effects.  On preferences we want something that can easily be re-used as built-in help.  Some effects don't need a page of their own, but some e.g. equalisation, definitely do.
 * Editorial Consistency: see Consistency
 *   generally a good thing (but not on FAQ page).
 * Gale doesn't like   as it's deprecated. Even now (Nov09) James still uses it sometimes....

Summaries of past discussions
JamesCrook 18:49, 28 November 2009 (UTC) If I've mis-stated anything here, it's open to correction. This is a wiki.

One-off Details

 * New order for items in Foundations.
 * We have both What is an Audacity Project? (user perspective) and Audacity Project Format (developer details, XML file structure). Peter and Bill both keen on having something about the XML.
 * The top of Playing and Recording is a duplication of Control Toolbar. We certainly don't want that duplication.

Screenshots

 * Images best as absolutely standard windows classic screenshots (i.e. not interesting shades of green).
 * Some screenshots, e.g. tracks, improved by drop shadows, but not a must-have.
 * Plans to automate screenshots better 'some time in the future'.
 * Backgroundless images for cursors can be extracted from theming output - i.e. they were not lovingly handcrafted :-)

Structure
There's at least three styles of writing in this manual.


 * There's the remnants of the old reference manual- not linked to directly from the main page, but still visible via the FAQ.
 * There's the detailed tutorial style of the main help.
 * There's some newer reference help that is brief.


 * James (earlier in 09): "The dividing line ... if you need a before-and-after image, then it does not belong in the reference section. As soon as you have a before-and-after it's doing 'steps to do XYZ...'. " and  "it's the switching back and forth between item->explanation, item->explanation and howto->step->step->step on the same page that I care about." (Nov 09) - but things have long ago moved on since I said that.
 * Bill 28Nov09: Look at the Edit Menu page. I think the before and after images there are indispensable. There's a difference between "before-and-after" and "step->step->step->step".
 * James 29Nov09: Yes, I agree. I like that use of the before and after.  Noise Removal is a good page too, and there we do need the two steps since getting the noise profile and removing the noise have to be explained.  So - even a no 'step->step' rule is not right.  In Noise Removal we don't need (and don't have) tutorial content on how to remove mains hum, tape hiss, breath sounds and air conditioning glitches.  Linking to such tutorial content, as we do for mains hum, is the right solution.


 * Gale: "As I've said before, much of our duplication problem is that the GUI is itself task-arranged to a large extent. We've agreed about the balance of reference information and how-to on Track Drop-Down Menu so I would not expect we'd disagree much about that balance on other reference pages."

Printed Manual Only
The following links will not be visible to logged-out online or in the dumped (installed) manual:


 * Title Page
 * Copyright
 * Introduction

Excluded from printed and online Manual
The following old/experimental pages will be excluded from both the printed manual and from the front page of the logged-out online/installed manual. They can still be found online through Search):
 * Editing for Beginners - Cut, Copy and Paste
 * Editing for Beginners - Introduction
 * Editing for Beginners - Silence, Duplicate and Split
 * Editing for Beginners - Splitting and Submixes
 * Sample rates (may be a candidate for a technical appendix or similar later)
 * Theme Preferences
 * Transcription Toolbar disabled
 * What's New in Audacity 1.3.2

James: I would like to remove this div from the front page. Please +1/-1 this proposal.
 * +1 Bill I've always wondered why it was here, except to preserve that list of pages. Can it live on the talk page?
 * +1 Peter love the new front page
 * James: Done. We might put the first part back later, if we re-instate pdf printed-version generation.