Hi Joe, All,
My comments are inline.
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.
>
I think many people can use or have access to Google Translate, or similar
software, so writing tersely isn't necessary, from a language point of
view. And, while I do agree that such a terse/crisp format can be
successful, there was no direction that this was necessary or even a
requirement. Lastly, if foreign language is the problem here, surely we
could recruit some DX helpers to translate for us- but I'm not really sure
how important that is or even how to go about it.
Alternatively, I'd be happy to run the doc through Google Translate and do
that sort of coding.
> 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."
>
Don't disagree with this at all. But it would have been nice to know at the
outset.
>
> 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.
>
It was uniform, so far as I could tell, so I'm a little puzzled by this
criticism.
And speaking of uniformity, in your editing, you've also introduced a
picture which isn't consistent with the others I used for the Configuration
Tabs, specifically the Radio Config pic. Was there something wrong with my
picture?
>
> 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.
>
I disagree, but I don't mind acquiescing to your view. Too much or too
little, it's a fine line, for sure. As it looks now, I think it's too
little and a bit disheveled, but it's a work in progress and I may change
my view when you get it finished.
>
> 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 think this will be an interesting approach, and I'll be interested in
seeing how it develops.
> 6. Special cases, "gotchas", etc., should be dealt with either in
> "Configuration Details" or in "Frequently Asked Questions".
>
While my view is that it is better to have similar subjects next to each
other or follow in a logical order, I suppose there could be some benefit
here in having to hunt for these outliers and yours may be a better
approach. Though, I suppose you could always link around in the document,
"if you want to know more, click here," etc. That seems a little obtuse to
me, but maybe it's the right way.
>
> 7. This Guide should be for v1.4. In general I see no need for
> references to earlier versions.
>
I think that's a good idea and Bill had a similar point of view. I would
caution that it might be a good idea to instead comment out the FAQ
leftovers instead of deleting them entirely.
>
> 9. We should make specific reference to the very useful (but Windows
> only) companion program, JT-Alert.
>
I had made a placeholder for this, but it's been deleted somewhere along
the way. Not sure why.
Back to moving boxes and newspaper!
73,
Chase
http://w4ti.com
------------------------------------------------------------------------------
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
