GNOME Bugzilla – Bug 693156
Request for enhancement to Tutorial and Concepts Guide
Last modified: 2018-06-29 23:13:25 UTC
1. In the Tutorial and Concept Guide Chapter 2(?) "The Basics" move the "Account Tree Window" and "Account Register Window" topics to the end of the chapter. 2. In "Toolbar Buttons" topic change the line "Register buttons are discussed in Chapter 4, Transactions. " to be another point line reading "Register specific toolbar buttons are discussed in Chapter 4, Transactions. " 3. Add another point line reading "Report specific toolbar buttons are discussed in Chapter 7 of the GnuCash Help Manual. " 4. Add another point line reading "Windows -- Presents a drop down list of choices New Window, New Window with Page and names of the currently selected tab in each open window. Each window can be minimized and may or may not be visible and have the focus as defined by the operating system user interface. If a window is closed the available tabs will fall back to the previous window except when the last window is closed." 5. Add another point line reading "Help -- Presents a drop down list of help choices." 6. After the "Toolbar Buttons" topic add another topic titled "Tab Bar" 7. Add the following contents to this new topic "The Tab Bar contains tab buttons representing the various windows that are open and available in this top level window. They can include the Account Tree window named "Accounts", the Scheduled Transaction Editor window named "Scheduled Transactions", the General Ledger window named "General Ledger", any report windows that are open in this top level window, and any account register windows that are open in this top level window. The contents of the top level window will correspond to one of the currently available tabs, which will appear to be highlighted. If the mouse pointer hovers over one of the account window tabs, a fully qualified account name will appear. If the mouse button 2 (right mouse button) is clicked while hovering over the tab bar, a complete list of all the tabs appears and any tab can be selected for viewing by using mouse button 1 (left mouse button) in the list. If the Window menu button is pressed and "New Window With Page" is pressed, whichever tab is currently highlighted will be removed from the current window and moved to a new window." 8. Consider adding topics for Scheduled Transaction editor General Ledger and reports. 9. I am not married to this exact text, but I would like to see comparable changes made to the Tutorial and Concept Guide
David-- You don't really explain why you want each of these changes, and I'm not sure about them consequently. My comments: 1) I don't agree. The windows are described in the order a user will encounter them (Tip of the day, Account Tree window, Account Register window). I don't see how moving them will improve anything. 2) I don't agree. The bullets outline different buttons on the toolbar, while the non-bulleted item discusses the class more generally. I think the solution might be to use the language you propose, just not bulleted. 3) This addition would be good. I suggest the same solution here as for 2. 4 & 5) This section isn't describing all the menus and their options, and so these don't belong here. I think there is a delineation of the menu items in the Help file, so I don't think these are necessary. 6 & 7) This would (I think) be useful and appropriate here, although the text you provide needs a lot of work. I don't understand entirely what points you're trying to convey. 8) Scheduled transactions are covered in chapter 4.6 9) ??? David T.
David Carlson, you need to defend your proposal or this bug will be closed as incomplete.
After reviewing this bug in the light of David T's comments, I believe that the gist of my discomfort with this chapter is that the topics are not assigned to the type of window where they appear or sorted in the order going down the window view. In the following proposal I use the words "top level window" to describe independent windows owned by the current instance of the GnuCash program and "account window" to describe the contents currently visible in the currently selected top level window. This is my revised proposal: 1. I wish to see major sections for each account window type (Accounts window, Account Register Window, Scheduled Transactions Editor window and Report window or a reference to reports). Each section would have subsections for Menubar items and Toolbar items in that order as the eye moves down the window. 1A. Alternatively, add a window type description for Scheduled Transactions Editor window after Account Register window description and move the current Toolbar items section after the Menu Items and Menu Shortcuts sections, each with subsections for the differences between the major account window types. Since the Toolbar is mostly a few shortcuts for the most commonly used menubar items, that could be pointed out in the first sentence of the Menubar description. 1B. Third alternate would be to add a window type description for Scheduled Transactions Editor window after Account Register window description and change the section title 'Toolbar Buttons' to read 'Toolbar Buttons which appear below the Menubar' 2. In "Toolbar Buttons" topic change the line "Register buttons are discussed in Chapter 4, Transactions. " to read "Register specific toolbar buttons are discussed in Chapter 4, Transactions. " 3. Add another line reading "Report specific toolbar buttons are discussed in Chapter 7 of the GnuCash Help Manual. " 4. Change the first sentence in the Menu Items section from "The account tree window and the account register window both contain menu headings in a Menubar. Clicking on a menu heading brings up the menu items for that heading." to "All of the window types contain menu headings in a Menubar. These are described in detail in the Help manual. Clicking on a menu heading brings up the menu items for that heading. 5. After the topics Toolbar Buttons and Menu Items/Menu Shortcuts Add a note "Note: It is possible to open additional top level windows. If the Window menu button is pressed and "New Window With Page" is pressed, whichever tab is currently highlighted will be removed from the current top level window and moved to a new top level window. If additional top level windows have been opened, each top level window will contain it's own specific Tab Bar." 6. Add a section titled "Tab Bar" containing the following text "The Tab Bar contains tab buttons representing the various windows that are open and available in this top level window. The tab that represents the current account window in this top level window will appear to be highlighted. If the mouse pointer hovers over one of the account window tabs, a fully qualified account name will appear. If more windows are open than there is room for in this Tab Bar, only a few tabs will be visible. Then if the mouse button 2 (right mouse button) is clicked while hovering over the Tab Bar, a complete list of all the tabs appears and any tab can be selected for viewing by using mouse button 1 (left mouse button) in the list." 7. Add a topic "Summary Bar" containing "Content varies with account window type. See Help manual."
The title of this RFE is "Tutorial and Concepts Guide". ISTM what you're asking for is appropriate for the Help document, which is our screen-by-screen and menu-by-menu manual. I think it's already organized that way, though there are very likely places where it's incomplete.
Created attachment 264916 [details] Proposed Interface description That is a good point, I think that some of the details in my comment 4 should be applied separately to the help manual. Since I am proposing a substantial change to the Tutorial and Concepts Guide that is too complex to see clearly in plain text, yet is not quite ready to be converted to a patch, I have composed an Open Office Writer document that represents the bulk of my proposal which would replace the Interface description in Chapter 2. Once this is polished it will be necessary to update the index and a few other details elsewhere when I convert it to a patch. I am attaching this document in a tarball. I hope it is readable.
David-- I see a mixture of minor and major edits sprinkled throughout the entire chapter. I see that you have rearranged the elements in the chapter, and I think the reordering is right. The first edit I see is a major one: your insertion of the sections for Scheduled Transactions and Reports. I have a couple of issues here. First and foremost, neither is what I'd called "Basic," and so I question adding sections to this chapter for that reason. Second, Scheduled Transactions are covered in chapter 4.6, and I think that if that doesn't work, the text there should be modified to meet your needs. Reports could use better documentation, and are the subject of a different documentation bug (633590) meant to address the documentary shortcomings for reports. The upshot is that I don't think these sections should be added here. Next, I see some minor parallel changes to the Menu Items and Toolbar sections. * I agree with changing the first sentence of the first paragraph in each section. I might propose using the locution "All windows in GnuCash contain..." * I am not convinced that it is necessary to add the information specific to the Scheduled transactions windows in either spot, although I admit that because I use a Mac, the right-click option is foreign to me. However, in each spot, the examples provided seem to me illustrative, and not exhaustive. In other words, I don't think it is necessary here to include every variation in the interface--just the basics. Finally, the section on the Tab Bar is a useful addition. I offer the following: Tab Bar GnuCash uses a tabbed model to to allow you to open multiple account registers and reports simultaneously. Each open account register or report has a tab that you can click to view. Tabs can be configured in Preferences to appear along any side of the Gnucash window. To see the full name for a tab, hover the mouse pointer over an account window tab. If more screens are open than can be displayed across the screen, some tabs will not display. You can move through all tabs by clicking the arrows on either end of the tab bar. A complete list of tabs can be viewed by right-clicking the Tab Bar and any tab can be selected by clicking it. * The final paragraph in this section (the Note about program windows) is unclear to me. I haven't experienced this. Perhaps it is not possible in the Mac world?
In further consideration, I suggest the following Tab Bar text, to be inserted after the Toolbar section: Tab Bar GnuCash uses a tabbed model to to allow you to open multiple account registers and reports simultaneously. Each open window (which can include account registers, reports, or the Scheduled Transactions {link to chapter 4.6} window) is given a tab on this bar that you can click to view that window. Tabs can be configured in Preferences to appear along any side of the Gnucash window. To see the full name for a tab, hover the mouse pointer over an account window tab. If more screens are open than can be displayed across the screen, some tabs will not display. You can move through all tabs by clicking the arrows on either end of the tab bar. A complete list of tabs can be viewed by right-clicking the Tab Bar and any tab can be selected by clicking it.
I note this bug is in "NEEDINFO" state for more than a year now. I read the proposed text and it looks fine to me. @David: feel free to convert this into a patch that can readily be included in the documentation.
I agree. I have not yet learned the correct procedure, so your help would be much appreciated.
Created attachment 298251 [details] [review] Tutorial Chapter 2 Basics edits
I have attached a patch that (one hopes) will address the concerns of David Carlson.
Anything?
I accept the proposed patch. Thank you David for your help.
Comment on attachment 298251 [details] [review] Tutorial Chapter 2 Basics edits Looks good, thanks! Pushed to maint, it will show up in the 2.6.6. release.
Reassign version to 2.4.x so that individual 2.4 versions can be retired.
GnuCash bug tracking has moved to a new Bugzilla host. This bug has been copied to https://bugs.gnucash.org/show_bug.cgi?id=693156. Please update any external references or bookmarks.