Talk:Main Page

From Audacity Manual
Jump to: navigation, search

Recent discussion on Front Page changes moved to Talk page

Peter 18Dec12: I moved the "Digital Audio" down to be the last item in the "Understanding Audacity>Foundations" section. It is indeed a "foundations" topic imo - but I wanted this section to provide greater focus on "Audacity Projects" which is a truly key topic, important for all users. The material on the Digital Audio page is useful and interesting background but not absolutely necessary for understanding the use of Audacity - apart, that is, from the final section on compressed audio - but we are attempting to deal with (some of) that in Audacity Projects.
  • Gale 18Dec12: I moved Digital Audio back up to third in line, as I hope a reasonable, logical compromise. I am fine with Projects first but on the -manual list I suggested we may even need a new, short Foundations page that addresses the export/save dichotomy directly, and moves Importing Audio and File Export Dialog up into "Understanding Audacity".
    • Peter 27Dec12: Ok deliberate baby steps today. Today's changes should be fairly uncontroversial - but can be reverted one at a time if though necessary
      1. First I added into the "Understanding Audacity>Foundations" section entries for "Importing" and "Saving and Exporting", as suggested by Gale as readers were not finding these lower down the page. I thought long and hard and decided to put "Saving and Exporting" on the same line for a couple of reasons: to link the two together and associate them in readers minds, and to reduce the number of line entries in "Foundations (to limit bloat).
      2. Then I made the subtitle "Details for importing and exporting" (in "More Details for the Project Window") links to importing and exporting - and removed the inline links. With #1 above the in-line links were somewhat redundant imo.
      3. Finally I renamed "What is an Audacity Project?" to "Managing Audacity Projects" as suggested by Gale.
    • Peter 28Dec12: More revertable baby steps today - but as they are in line with Gale's suggestions in the email thread and in his strawmen should remain reasonably uncontroversial.
      1. In "More Details for the Project Window" I changed "Details for importing and exporting" to "More Details for Importing and Exporting" - as suggested by Gale.
      2. In "Understanding Audacity" I put "Audio Tracks" and "Waveform Display" on the same line as in Gale's strawman V2 (and V1)
      3. In "Understanding Audacity" I Removed "Saving Audacity projects and " from "Saving Audacity projects and Exporting audio files" as per Gale's suggestion in the email thread and in his strawmen.
    • Peter 29Dec12: Yet more revertable baby steps today - also in line with Gale's suggestions in the continuing email thread.
      1. In "Understanding Audacity" I moved "Audio Tracks and The Waveform Display" up in this block - in line with Gales's suggestion in his strawmen (but not indented).
      2. I moved "Findinding the correct effect ..." down into the "Editing" block as agreed to by Gale - and added links to Generators and to Analyzers.
      3. I changed "Quick Where and How" to "Quick Help" - now this section is trimmed it is not really a "where&how" - furthermore "Quick Help" ties in with the command in the Audacity program.
      4. I moved "Toolbars Overview" to the top of "More Details for the Project Window" as agreed by Gale. This required adjustment of the vertical margins above each div (see the diff for how this was done).
    • Peter 30Dec12: just one revertable/editable baby-step today:
      1. I copied in the info text from Strawman v4 for the two entries in the Foundations section. Based on Gale's suggestions with some modifications.
    • Peter 30Dec12: Today's baby steps
      1. In the "Tutorials" section I trimmied redundant explanatory text on "Example Workflows"
      2. In "Tutorials" & "Understanding Audacity" I applied consistent capitalization in the explanatory texts
      3. I implemented Gale's suggested revised FAQ box from strawman v4 - and accordingly trimmed the "Quick Help" - imo this looks much better - the "Quick Help" section looks nicely focused on "Getting Started - and I think the FAQ link and it's box get more prominence.
      • I think this probably draws this current round of Front Page changes to a close. Remember that we started this to try to help in the confusion that exists amongst users between "Save" and "Export" - it may not be perfect, but I think we have moved in the right direction. At some stage we still need to think about where LAME/FFmpeg/ODL/Metadata live on this page, but we can do that later.

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:
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!

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 [email protected]). In the footer? Or a link to [email protected] 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.

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

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

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.

  • 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
  • __NOTOC__ generally a good thing (but not on FAQ page).
  • Gale doesn't like <blockquote> 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


  • 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 :-)


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:

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):

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.
Personal tools