On 23/07/2014 19:19, Joe Taylor wrote: > Hi All, Hi Joe, > > As you will have noticed, I've been busy with other obligations > recently. I expect to have some time for WSJT-related matters in the > next few weeks, so I'm trying to get plugged in once more. Me too. > > Many thanks to Chase, W4TI, for all the effort put into the WSJT-X Users > Guide for v1.4. As you will see in the latest commit, r4210, I have > been editing the early part of the Guide -- the present Sections 1-4 -- > and have changed things quite a bit. I want to give you some feeling > for my underlying rationale for these changes. > > 1. To be most useful to the largest possible number of users, including > those whose first language is not English, I think the User Guide should > adopt a rather terse style: Do this, Do that, etc. > > 2. We should be uniform about "voice" and who we're talking to. Write > "You can set *Parameter X*" or simply "Set *Parameter X*", rather than > "*Parameter X* can be set by the user." > > 3. Use of colors, special fonts, etc., should be uniform. I've tried to > be consistent in using adoc formatting commands like *Bold Blue* for the > names of on-screen controls or parameters, and _italics_ for the > identifying names of groups of controls on our GUI. See, in particular, > the new Section 4 for many examples. > > 4. Early parts of the Users Guide should be short and sweet: enough > information for reasonably adept users to get started, but not a lot of > extra descriptive material about "why", or special cases. > > 5. Detailed descriptions of some options -- especially those whose > functions will be obvious to experienced users -- should be moved to a > section of their own. In r4210 I've made a dummy Section 9, > "Configuration Details", that might serve. I agree. Personally I like a recipe like format for the up front docs that might get the majority of users up and running by following a few basic set up steps. Also a detailed reference section with navigation links from the earlier recipes that covers all the options necessary to get all the oddball rigs and usage scenarios up and running.
Somewhat cynical but, in my experience "experienced users" don't read the manual anyway. > > 6. Special cases, "gotchas", etc., should be dealt with either in > "Configuration Details" or in "Frequently Asked Questions". > > 7. This Guide should be for v1.4. In general I see no need for > references to earlier versions. Definitely, release notes do that job in the correct context. > > 8. I will move on soon to Transceiver Setup and following sections. > Like the other early sections, I think this one should be short and > sweet. But even within that constraint, the present text can surely be > improved. We can also add extra help in the FAQ section. Although I feel (and I think you do to) that JT9 should be the mode of preference it is the case that JT9 operating requires a bit more knowledge and set up due to historical reasons and TX filter limitations. Because of that and the larger amount of activity on HF in JT65 I feel that the first tutorial should be based around a JT65 only example .WAV file. Then a dual mode tutorial as we have now which introduces the set up of the waterfall to 4kHz nd the JT65/JT9 split. Then a third turtorial using the current JT9 only example file targeted at users with limited RX bandwidth options explaining the +2kHz check box. Despite starting with JT65 I think the above may encourage a few more users to give JT9 a try which in the longer term will allow more users to share the bands. > > 9. We should make specific reference to the very useful (but Windows > only) companion program, JT-Alert. > > Comments on any or all of the above will be welcome! > > -- 73, Joe, K1JT 73 Bill G4WJS. ------------------------------------------------------------------------------ Want fast and easy access to all the code in your enterprise? Index and search up to 200,000 lines of code with a free copy of Black Duck Code Sight - the same software that powers the world's largest code search on Ohloh, the Black Duck Open Hub! Try it now. http://p.sf.net/sfu/bds _______________________________________________ wsjt-devel mailing list wsjt-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/wsjt-devel
