Talk:Main Page
Editorial Consistency
see Wording
Page Families
latest replies are below in this font ....
OK. So we'd like to be consistent in page formatting. We have:
- Family of pages for Preferences: I'd like to propose that we use headings for naming the static boxes, e.g. ==Recording== for the static box named 'Recording' and then bullet points for the items within the static box, i.e. we follow the design of Audio IO Preferences. I've been using two layers of bullets in some of the other preferences pages.
Update: after discussion on devel-list about accessibility issues, I think we should settle for James' plan which means ==name of static box or panel section== then a bulleted list for items within the static box or panel section. The first text in each list item should be the name of the item within the box or section, in bold. Using ===item within static box=== is another accessible solution, but it takes twice as much space and if we have a contents box, will make that so long as to be very intrusive for sighted users. Possibly this solution should be adopted for Menu pages as well (i.e. second order header then bulleted list of menu items within each section). However I'll gauge opinion on the list first - Gale
Reply by Gale: James, thanks for comments. I don't especially like headings on the Preferences pages (in fact on one such page - will have to check which - they got so much in the way that I got rid of them). They also looked very odd as there was not much text, so that the "Contents" was one-third or so of the height of the page. In those circumstances, I think headers are questionable, and pragmatism is better, but do screen reader issues mean we have to have headings irrespective? Can/should Contents sections be suppressed in the printed version only, or must it be forced with __NOTOC__ on the page?
I'd be fine with using __NOTOC__ liberally, if you think it looks better. I wouldn't be surprised if we can turn it off globally. I would expect decent screen readers to be able to give a summary of headings, even with no toc in the text, so wouldn't see it as being critical to screen readers. JC.
Another thing about headings is the size. We normally seem to use == (h2) for the first order and down from there but this is not always consistent and sometimes even authors that use it forget and use = (h1) for first order in the same page. I tend to prefer h1 then h3 for second order ignoring h2. This is because with h3 being bold it kind of looks more important than h2, given h2 is not very much larger than h3... but I don't have strong views. Some people like h1 then h2, but that means second order is underlined as well as first. I think the objection to h1 is the size relative to main text?
Great. OK, we do NEED to be consistent. My long term plan is to have some way that in Audacity you can click on a static box (in preferences) and have the appropriate part of the html help scroll into view. And equally click on the html page and have the static box 'highlight'. For that to work easily we need some way that a dumb program can tell which pieces of the html to link with which pieces of the preferences interface. And that means being consistent. I'd like to standardise on h2, given you don't have strong views and purists might not like the 'missing' heading level. Someone more knowledgeable than me can probably fix up the appearance later using style sheets.
H2 is the safest solution taking accessibility into account (much as I dislike the underlinings in Wiki). So I think that means when you are writing text, use h2 as your main headings (h1 is taken by the page title), and use h3 for a lower order header (or bullets in many cases, as per Preferences pages). I agree "sooner the better" for context-specific help (helps us limit "verbosity" in the program if we don't have to attempt explaining complex matters in one sentence).
- Family of pages for Menus: I like the three column table layout used in Track Drop-Down Menu, with the image of the menu on the left, the names of the items in the middle column and descriptions in the right column. However, it may not work well for pages which need long descriptions for each menu item. Perhaps we should do 'the same thing' as for preferences and give:
- The image, and then
- Headings for each section within the menu, and then
- Bullet points for menu items within each section?
I quite like the three column style too (actually four columns because columns two and three must be space-separated for it to look decent). On that page, "Set Rate" actually has two paragraphs and it still doesn't look bad. Another problem with "image, then headings underneath" is that it looks pretty odd because the image will be tall in relation to width (and it wastes space). But again if we must have headings for screen readers we may have to rethink...
There must be ways to make tables screen reader friendly.
My first preference is that we plough ahead with table based layout, and worry about how to make it screen reader friendly later. It's quite probable that using ! instead of | to get a header will be enough in this case (no nested tables).
From David B's feedback using ! with a single un-nested table, (though he didn't specify), he doesn't seem to regard the <th> tags this produces as very helpful.
- If you strongly disagree, then I vote we ditch the images of the menu because it will be too far away from the text to be useful. On the long menus it may already be a bit of stretch as it won't stay exactly lined up.
I prefer like you to persist with tables for now (in principle) and at least get text written. For long menus, we might for example include at the top an image of only the top of the menu, then have images of the particular menu sections alongside their section text.
Do we need to stick to the same style of Windows images (many of which are now my "classic XP with custom light green")? Is that colour itself an issue (if I would be better redoing with MS grey I don't mind, as long as we decide now). As you said, File menu probably wants a Mac image as well as Windows, given the differences.
I'm OK with the light-green theme going into the manual. I don't think we need to stick to the same style of windows image for 1.4.0 documentation. If we were starting afresh I'd suggest using absolutely standard Windows XP themes. If when we complete the manual other people on audacity-devel object to light-green, we tell them to go recapture all the screenshots themselves. At some point we will be able to generate all the screenshots off a single script, which will help when we update for new versions of Audacity.
- Hmm. We probably need to decide how we want to handle the effects list before we proceed. My thinking is that in a later edition of the manual we will have a page for each effect, with screenshot, explaining the parameters, and probably auto-generated. Therefore a short description of the effects is appropriate here. As an interim measure we could maintain the two versions (short and long) and cross link from the short to anchors on the long.
Whatever we do for 1.4.0, I am convinced from long-term feedback that the effect descriptions in the 1.2 manual (at least the more complex effects) were inadequate. The Equalization effect is now very complex and I can hardly see what you could usefully say in two or three sentences beyond describing its general purpose and its two views. I want to try and improve on that. Also we should bear in mind the poor take-up of updated versions (whether due to -announce list problems or whatever) may mean that people will stick with 1.4.0 longer than we intend. On the other hand some effects barely justify their own page. I don't object if they do have such, but if we were to lay out a small screenshot of the simpler effects to right of the text I don't think it would add that much to the length (but would aid comprehension and possibly reduce text). To do so properly needs tables though because of the strange ways Wiki images align themselves. I don't think deciding the ultimate means of display and layout for effects and the other menus holds up working on the text. A final decision is easier when the text and some images (if we have them) are there.
OK. For 1.4.0 we just continue as now. Some complex effects we put on a page of their own, and they have an image. Some simple effects are described in full on the main effects page, and they don't have an image. Some time in the future, but not for 1.4.0 we'll probably standardise on a separate page and parameters screenshot (where such exists) for each, because that's going to be easier to manage and update from a script.
- Could still be three column if we use <blockquote> for column three.
Blockquote is deprecated in XHTML so probably we shouldn't. I'm not sure how consistent the results of that or indenting with a colon are on different font sizes, but I think it will give too much space. - Gale
Oh. Didn't know that. I don't really care what we do as long as it looks nice visually. I'll even stay with the extra columns if that's what you think we should do. Priority order (for me) is Content, Looks, Consistent, Screen-Reader-Friendly, Not-Deprecated, Simplicity of mark-up.
- Family of pages for Toolbars: Should we use Control Toolbar as the prototype? What I like here is the use of just the button icon without the button background. It makes the section describing each button take little space. It encourages us to keep it brief.
Yes I like this too and not the old headered text underneath if we "can" get rid of headers. This is another page where (for sighted users) a Contents section seems redundant to me. Are these images of buttons without background in the source (i.e. not lovingly hand-cropped?).
Not lovingly hand crafted. You can actually generate them from the 'preferences tab', (find the last beta you have that still has it), then generate separate images.
Gale, these are just suggestions, so that we can fix on something. I think it's more important that we are consistent than what those choices of consistency are. JamesCrook 04:45, 9 December 2007 (PST)
Structure
Audacity Selection and Selecting are similar pages both linked to from the Main page. Is this overlap what we want? (probably yes, but just checking). JamesCrook 15:23, 24 November 2007 (PST)
No - Selecting has been deleted and I'll merge any differences into Audacity Selection - Gale
On the Tools Toolbar page I've linked the individual tools to the comprehensive articles on the topic - e.g. for envelopes and for selecting. Should we do the same for the links on the main page rather than create new short pages for these tools? JamesCrook 15:23, 24 November 2007 (PST)
I can certainly see the top of Playing and Recording is a duplication of Control Toolbar. We certainly don't want that duplication.
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.
I'm thinking the reference section needs to stay brief, so that anyone can quickly see what the features are by reading the reference section. To understand how to use the features they'll either start in the tutorial sections, or get to the tutorials from links from the reference section. The old reference material is gradually deprecated as we replace it with newer stuff. Sound OK? JamesCrook 16:31, 24 November 2007 (PST)
Reference section looks quite verbose to me in places e.g. the Effects section in the Reference is longer than Applying Effects in "Using Audacity" and there is quite a bit of duplication. Splitting Stereo Tracks has no corresponding section for the Track Popdown Menu in Reference? Editing: Cut, Paste, and More in "Using Audacity" looks like a duplication of Edit in the Reference. I think this needs a serious rethink and I don't think the Reference section in many cases can even be useful unless it describes all the menus and Preferences properly (and non-geekishly). I'm beginning to wonder if we need more (or longer?) "Tutorials" - something along the lines of the sections of "Using Audacity" but integrated into a real life scenario. For example there might be "my first session editing an audio file" and so this includes importing, editing and export/save (but split sufficiently that sections can be accessed individually or returned to). Then instead of "Using Audacity", a proper "How do I ..." index (links only, no descriptions) that people can go to for how to do an exact thing. Examples of this would be "recording..//choose mono or stereo recording" (goes to Reference: Audio I/O tab of Preferences) "create a new track" (goes to Reference:Tracks Menu).... "recording..// adjust input levels" (goes to Tutorial:My first recording).
Gale
Archived discussion
The dividing line I'm taking is that 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...'. I myself am comfortable with a separate page Editing: Cut, Paste, and More, and linking to it rather than incorporating it in File Menu or Edit Toolbar. I do regard Editing: Cut, Paste, and More as tutorial material, albeit tutorial-lite. Your way could work too. At the moment the reference section titles are all specific widgets or GUI elements. I like that. The 'book' organisation will take ONLY the pages linked here directly from this page, and in the order they are linked. If you mix some tutorial-lite sections in with the reference section without page-merging, the titles of those pages must appear in that section of this page. I'm not radically opposed to your plan, it does have lots of merit. However, there'll still be some topics that are tutorial-lite and aren't reference, so I don't think it solves anything.--James
Sure, I'd entirely envisage there would be some sections that are tutorial-lite and not reference. However as an example, moving the Applying Effects link to somewhere under "Effects" in the "Menu Bar" reference would help reduce the sections of the front page which have these tutorial-lite links. My feeling is to keep those sections as short as possible, and let them contain only links that don't naturally attach to an individual link in the reference section. We examine the links we currently have in the tutorial-lite sections of the front page to see if they can be merged into current reference pages without overburdening those pages. I think we still play this by ear really. My concern is that the sections of the front page containing these tutorial-lite links are not all that clear as to their purpose and as to how they differ from the reference. It may be that refining their categorization them and/or dreaming up a generic title that distinguishes them from Reference (maybe even using another word than "Reference") might help.- Gale
I know there are lots of images but we just put a load of images in Track Drop-Down Menu? - Gale
When we've done all the topics on the Track Drop-Down Menu page, we might find we want to move the audio-tracks part to Audio Tracks. We'll see. It's not the number of images that matter, 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--James.
We may well want to make that move (or more likely, live with part-duplicating the vertical scale explanation on Track Drop-Down Menu and Audio Tracks). The latter needs to say it as well I think. Again, we'll see about merging the contents of Editing: Cut, Paste, and More inside a current reference page. It may or may not work (for the reason you state), but should be considered. Again, remember that if well done, many users may well prefer some how-to on the same page rather than shunting to a different page.
Why is "Smooth Volume Changes...'" a section on its own when say "Moving tracks and clips with Time Shift Tool" isn't? Because of the length? Logically, that is not a very good justification IMO. - Gale
History, I'd say. In my view both deserve a page of their own. Tools Toolbar should be linking to reference pages on each. As we do not have a reference page for envelopes and do have a tutorial page already, it's less work to link to the tutorial. It says more than a reference page would, but that's acceptable for the saving in work. We're not mixing styles on the same page.--James
Time Shift Tool is a reference page on its own now, of course. But in my view "Smooth Volume Changes" should not be linked to in the tutorial-lite section of the front page just because it happened to be written in part tutorial style, but in the Reference section of the front page. We already agree "Compressor" is linked to in the Reference not in the tutorial-lite sections (although to be really useful, it will I think have to include some how-to material). That is, we don't want to end up linking to it in the tutorial-lite section as "Dynamic range reduction with the Compressor".
I do think we have to be flexible about Toolbar pages as to whether GUI items in a particular toolbar have their own page or not. IMO it would be duplication for Zoom Tool to have its own page as there is not much you can say about it in the first place.
I would have a "Foundations" section and "Other Features" or similar for things that are specific yet wider than (so don't logically relate to) a Reference page. Everything else is a link-out from a Reference page in an appropriate place e.g. "Applying Effects" is under Effects in the Reference. Splitting Stereo Tracks is under Tracks. And even then, *only* if they cannot be conveniently merged into the detailed text in the reference page. - Gale
Applying Effects as currently written is definitely Tutorial content. The reference for the Effect Menu already says:
To apply an effect, select part or all of the tracks you want to modify, and select the effect from the menu. Titles which end in an ellipsis (...) will bring up a dialog asking you for more parameters.
That is all a reference needs (or should) say. Pretty much agree. Effect Menu can link to the tutorial on Applying Effects, but that does NOT belong in a reference section.
I entirely agree for much of that content. What we're arguing is the case that the *link* to Applying Effects on the front page should be placed in the Reference section, not in the confusing tutorial-lite sections. Looking at the content of Applying Effects, it looks to me mostly like an historical appendage we don't even need now. It's more a tutorial for using Amplify tool, if it's any use at all. So rather than keep it as is, I'd think we (I) should merge/rewrite whatever is useful in it somehow. It's perfectly possible to do that.
We should consider the other page-mergers case-by-case. If we can lets keep the reference as it currently is as an anatomy of the GUI, organized in terms of the GUI itself rather than in terms of tasks.--James
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. - Gale
