Re: [Qlandkartegt-users] What should be contained in the FAQ?

[Dr Rainer Woitok]

Wolfgang,

On Sunday, 2016-12-04 08:43:54 +0100, Wolfgang Thämelt wrote:

> ...
>  > Using a numbered list rather than "##" headers more or less empties 
>  > the "[TOC]" section.
> 
> Yes, of course. But: the manual main page DocMain consists in principle 
> of the detailed TOC.

Now it's my turn to say "Yes, of course.  But:" :-)

When you now open "DocMain"  in your browser  you just see a big picture
and you have  to manually  scroll down  to get to the  real information.
Formerly you saw a somehow reduced  table of contents and you could imm-
ediately move to the  section you were interested in  by clicking at one
of the lines in the "[TOC]" section.

Sincerely,
  Rainer

--
___
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users

Re: [Qlandkartegt-users] What should be contained in the FAQ?

[Wolfgang Thämelt]

@Rainer:

Some comments to your proposals/remarks:

 > Using a numbered list rather than "##" headers more or less empties 
the "[TOC]" section.

Yes, of course. But: the manual main page DocMain consists in principle 
of the detailed TOC. The automatically added [TOC]
at the topic of this page would simply duplicate the entries in the 
detailed TOC (at least those with a header line).
With the numbered list this duplication is avoided.

 > moving the list of hotkeys from section "Advanced Usage" into the new 
"Appendix" section?

Done.

Regards

WolfgangTh





--
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
___
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users

Re: [Qlandkartegt-users] What should be contained in the FAQ?

[Dr Rainer Woitok]

Wolfgang,

On Friday, 2016-12-02 17:04:29 +0100, Wolfgang Thämelt wrote:

> ...
> please have a look in the QMS wiki!

To give you some quick feedback  regarding my first impression from just
reading "DocMain.html" (I didn't yet get any farther :-):

   - Using a numbered list rather than "##" headers more or less empties
 the "[TOC]" section.

   - I would  suggest moving the  "Installation" section ahead of "Basic
 QMapShack usage".   After all "Installation" isn't "Usage", neither
 basic nor advanced.

   - What do others think about  moving the list of hotkeys from section
 "Advanced Usage" into the new "Appendix" section?  And what do oth-
 ers think about  additionally listing  the relevant hotkeys under a
 last header  "### Useful Hotkeys"  in each of the other pages where
 this makes sense?  Is using hotkeys really "advanced"?

   - The new "Appendix" section  seems a good  idea to me.   I think the
 "Glossary" page you already mentioned should also be anchored here.

   - Since it  is quite  clear from  the very  beginning that  this is a
 "QMapShack" manual,  we could perhaps remove  "QMapShack" from most
 of the section headers and link texts (like "Advanced QMapShack us-
 age" or "Troubleshooting QMapShack").

Sincerely,
  Rainer

--
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
___
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users

Re: [Qlandkartegt-users] What should be contained in the FAQ?

[Dr Rainer Woitok]

Oliver,

On Friday, 2016-12-02 13:58:40 +0100, you wrote:

> ...
> The basic stuff is always:
> ... [ long list of things omitted ] ...
> This is reflected more or less by the current Wiki structure.

I agree that your listing  includes probably everything currently docum-
ented under the  "Using QMapShack"  header.   The big  question then is:
What are we going to put into the planned new "Advanced Use" section?

Sincerely,
  Rainer

--
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
___
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users

Re: [Qlandkartegt-users] What should be contained in the FAQ?

[Oliver Eichler]

> As a start I would suggest to move "Command line parameters", everything
> "DEM" related, "Working with Projects", "Database", and "GPS Devices" to
> the "Advanced Usage" section.   This currently leaves  "Getting started"
> and most (but probably not all) of "Tracks, Waypoints & Co" in the "Bas-
> ic Usage" section.   Sadly though, even the  "Getting started"  page al-
> ready talks about DEM files.


The general user's expectation is to get something like in the first
picture of the Wiki as quick as possible:

https://bitbucket.org/maproom/qmapshack/wiki/images/maproom1.png

I know that from giving hands-on sessions and from analyzing the blogs
about QMS.

The basic stuff is always:

* Where to get it?
* How to install it?
* What's on the GUI the 1st time you start?
* How can I reorganize the GUI to my liking?
* How do I get/integrate maps? (existing maps: raster and Garmin maps,
and OSM as preferred online map)
* How do I get hill shading (and elevation on tracks etc.) -> boils down
to install DEM
* How do I setup routing? -> usually they don't know that they want to
do it now, but it's the right point to do it now.
* How to load GIS data? (file and device) -> as many users are still
used to item lists, the idea behind projects has to be explained.
* How can I create waypoints, tracks, routes -> at this point routing
and DEM data must be already installed.

Stuff not asked by first time users but I think it's important to know
right from the beginning:
* How to use the database. -> Users tend to use the workspace as
database. But that is dangerous as you can remove the data very easily
by accident.

And of course Garmin and TwoNav users want to know how to use their
devices -> for them this is basic knowledge

This is reflected more or less by the current Wiki structure. Of course
the Wiki was not written with precisely that list in mind. Rearranging
it might be advised. But I do not agree on dropping important basic
content like DEM, routing data and projects. And even if the database
and the devices are not of everyone's concern they are important to
those using them and they expect basic explanations when starting with QMS.









--
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
___
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users

Re: [Qlandkartegt-users] What should be contained in the FAQ?

[Dr Rainer Woitok]

Oliver,

On Wednesday, 2016-11-30 18:29:14 +0100, you wrote:

> ...
> I agree on splitting the user related stuff into 3 parts. "Basic Usage",
> "Advanced Usage", "FAQ" are a good suggestion for the major headlines.

My suggestion would be  to leave the  FAQ in the  "Getting Help" section
where it already is.  But since we want to switch from the current head-
er "Using QMapShack" to "Basic Usage" and "Advanced Usage" I would sugg-
est to slightly rename the other major headers, too, as in:

# Installation
# Basic Usage
# Advanced Usage
# Help
# Development

> "Basic Usage"
> 
> The goal is to get a novice user up and running as fast as possible. And
> to display the possible features of QMS to give an overview.

As a start I would suggest to move "Command line parameters", everything
"DEM" related, "Working with Projects", "Database", and "GPS Devices" to
the "Advanced Usage" section.   This currently leaves  "Getting started"
and most (but probably not all) of "Tracks, Waypoints & Co" in the "Bas-
ic Usage" section.   Sadly though, even the  "Getting started"  page al-
ready talks about DEM files.

> ...
> Pictures: I think the major caveat of the current images is the naming.
> maproom1...X.png is not a good idea.

Strictly speaking,  naming picture files is not a documentation issue in
that the user doesn't see these file names.   Well, at least I don't see
them using Firefox.  Using meaningful names is "only" relevant for main-
taining the documentation.

>  It's better to give them a caption
> and to use the caption as file name.

I object.  Since there is a good chance  that captions contain blanks or
other characters not allowed  in file names or URLs,  this doesn't sound
like a good idea to me.

>  Another problem I always have with
> images is to reproduce them.
> ...
>Maybe we should test some tools and commit the
> setup data to the repo.

Including the source GPX files they are taken from.  But that would mean
to somehow anonymize them or to use manually created tracks.  At least I
wouldn't like to document in a public wiki repository  at precisely what
time I've been in precisely which place.

Sincerely,
  Rainer

--
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
___
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users

Re: [Qlandkartegt-users] What should be contained in the FAQ?

[Oliver Eichler]

Ok, I had a look.


I think, too, that a linear list is better because it's more verbose.
You see the list and you know all headlines. You can even search that
very easily.

I agree on splitting the user related stuff into 3 parts. "Basic Usage",
"Advanced Usage", "FAQ" are a good suggestion for the major headlines.

"Basic Usage"

The goal is to get a novice user up and running as fast as possible. And
to display the possible features of QMS to give an overview.

"Advanced Usage"

The goal is to show the user how to solve complex tasks by combining the
features, e.g. "How to plan a route/track", "How to re-organize data
between several projects", "Example setup of a database"

"FAQ"

Real frequently asked questions like "Limited digits". "No calculated
route support for devices." Probably everything that is not available,
therefore can't be documented but has a good reason for not being available.



Pictures: I think the major caveat of the current images is the naming.
maproom1...X.png is not a good idea. It's better to give them a caption
and to use the caption as file name. Another problem I always have with
images is to reproduce them. You change a bit and you have to get the
app window to the exact size and position the screen shot rectangle. And
if you had some annotations like arrows and numbers you can draw them
all again. That sucks. Maybe we should test some tools and commit the
setup data to the repo.





Am 29.11.2016 um 13:22 schrieb Wolfgang Thämelt:
> Please look at
>
> https://bitbucket.org/maproom/qmapshack/wiki/playground/DocMainTest
>
> for a proposal of a possible re-organization of the QMS manual.
>
> Feedback welcome!
>
> Greetings
>
> WolfgangTh
>
>
> --
> ___
> Qlandkartegt-users mailing list
> Qlandkartegt-users@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users


--
___
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users

Re: [Qlandkartegt-users] What should be contained in the FAQ?

[Dr Rainer Woitok]

Wolfgang,

On Tuesday, 2016-11-29 13:22:14 +0100, Wolfgang Thämelt wrote:

> ...
> Feedback welcome!

Here you are :-)

Good ideas:  Adding section "Glossary"  and splitting  "Using QMapShack"
into sections "Basic Usage"  and "Advanced Usage"  (my preferred titles,
though I'm open for discussion).  The main task remaining then is to de-
cide which topics  covered anywhere  in the current section "Using QMap-
Shack" are basic and which are advanced.

Bad idea: Converting the linear  table of contents ("DocMain.md") into a
hierarchical structure.  I really don't see any benefits in keeping "the
contents list in  DocMain.md short".   After all,  scrolling down a page
(regardless of whether  you are doing it via  your mouse's scroll wheel,
via pressing the space bar or the "Page Down" key,  or via operating the
browser's scroll bar with the mouse) is an operation which is by magnit-
udes less expensive  than opening several  new pages by  clicking on the
corresponding links.

Adapting my scripts to such a hierarchical structure is doable but isn't
trivial.  Scripts "DocFix.sh", "NavBar.sh",  and "HtmlMake.py" are norm-
ally run from the makefile on only those files requiring it.  So the re-
cursion has to be implemented via recursive makefiles, and that requires
keeping the "*.md" files themselves  in a directory tree  reflecting ex-
actly the hierarchical structure of the new table of contents.

Script "LinkCheck.sh"  would require  to use  the "find"  command rather
than just "*.md" and to explicitly avoid directory "playground/".

These are just  my first thoughts  about implementation ...  as a German
proverb is saying: "Der Teufel steckt im Detail" :-)

Sincerely,
  Rainer

--
___
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users

Re: [Qlandkartegt-users] What should be contained in the FAQ?

[Wolfgang Thämelt]

Please look at

https://bitbucket.org/maproom/qmapshack/wiki/playground/DocMainTest

for a proposal of a possible re-organization of the QMS manual.

Feedback welcome!

Greetings

WolfgangTh


--
___
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users

Re: [Qlandkartegt-users] What should be contained in the FAQ?

[Oliver Eichler]

Hi,

the documentation was written with a first time user in mind. That's why
the topics start with the "first start" experience and move on to
installing/handling maps. Next it explains the general idea behind
projects and the 4 elements a project can contain. I recommend to read
the wiki up to this point for everyone. The database is not a must. And
devices only of interest if you got one that is supported.

Most of these topics I wrote while developing the software and
occasionally updated it. Thus it's not always up-to-date. And it's more
a documentation about what is available. Less a documentation about work
flow.


Many of Wolfgang's FAQ articles compensate that lack of work flow
documentation. These parts would fit better right into the real
documentation. Maybe in a different font to mark them as work flow
documentation vs what's available documentation. I am not sure if we can
squeeze that out of the Markdown tags.

The FAQ probably should contain answers to questions that will not be
documented e.g. why there are not a trillion digits behind the colon.
There is no sense to explain that in the documentation. But it's quite
frequently asked and has to be answered.


But always keep in mind that the docs are for new users in the first
place. Thus keep it short, keep it simple. Place the important stuff in
the first paragraph rather than in between a lot of side information.
The strong reader will find the details while reading the complete
article. And for the weak one I am happy if he/she gets the basic idea
without reading everything.


One thing I personally dislike in the Wiki are the images. Images are
important but they are a pain in the ass to keep them up-to-date and to
organize them. Plus I think I made a real bad start with the naming
scheme. If you guys have a better idea go for it.


Oliver




Am 21.11.2016 um 20:33 schrieb k-w.thaem...@web.de:
> Hallo Rainer,
>  
> you raised this problem at the right time. I already started thinking
> about the future of the FAQ in the same direction as you did. There
> are certainly quite a few topics that belong to the "basic" part of
> the documentation.
>  
> Up to now it was relatively easy for me to insert information into the
> FAQ part of the Wiki. Here topics are and can be isolated. There is
> more or less no need to think about the right place in the
> documentation, the interference with other parts and so on.
>  
> My intention was to share with other users insight into QMS that I got
> while working with QMS (following Olivers call for contributions).
> And, of course, I played with QMS triggered by various discussions in
> the newsgroup and elsewhere. Thus, my QMS information comes from a
> users point of view and not from the designers/coders view (but I know
> that Oliver reads the contributions quite carefully and if there is a
> need he comments on them).
>  
> With regard to your proposal I see at least 2 questions which should
> be discussed before somehow re-arranging the Wiki:
>  
> * The list of contents of the Wiki in DocMain is relatively short and
> should certainly be extended due to the fact that QMS has plenty of
> useful features not yet described (some are now in the FAQ). Otherwise
> the Wiki pages are getting too long. And above of this: The structure
> of the list of contents should reflect the philosophy of the software
> designer!
>  
> * What is the best structure for the QMS Wiki? Is the linear structure
> proposed in connection with your toolset the best way to describe QMS
> or would a tree structure as normally used in Wikis to be preferred? I
> don't know how to answer this question. Both approaches have their
> pros and cons. Think what happens with the DocMain page when having
> there a much longer linear list of contents required by your tools!
>  
> Thank you for raising this discussion!
>  
> WolfgangTh
>
>
> --
>
>
> ___
> Qlandkartegt-users mailing list
> Qlandkartegt-users@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users


--
___
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users

Re: [Qlandkartegt-users] What should be contained in the FAQ?

[Günther Bosch]

I fully agree. FAQ really should be slim in order to reduce the double
effort when updating.
I think the best solution is that the FAQ give a short intro into the
topic, very general. And provide a link to the actual documentation.


Günther Bosch
+43 680 3392124

On 21 November 2016 at 17:20, Dr Rainer Woitok 
wrote:

> Greetings,
>
> since about mid of August  Wolfgang has collected  a wealth of informat-
> ion, tips, tricks regarding QMapShack  and put it into the various "Doc-
> Faq*.md" files.
>
> But is the FAQ the right place for ANY kind of information?   I mean, we
> could put everything into the FAQ: how to download QMapShack, how to in-
> stall it, how to report a bug, how to write documentation.   But I don't
> think that's what a FAQ is made for.  The four topics mentioned just ab-
> ove clearly should go  into the regular documentation,  and in fact they
> do, as far as the QMapShack documentation is concerned.
>
> To explain more precisely what I'm up to let's take file "DocFaqHandling
> .md" as an example:  the various tricks to find distances between points
> probably belong in the FAQ (even though I think QMapShack should provide
> an easy to use  tool to measure  the distance between  two points rather
> than requiring creation, projection, and deletion of a waypoint) whereas
> information about selecting a range within a track should -- in my opin-
> ion -- be contained in file "DocGisItemsTrk2.md",  where most users most
> probably would expect it anyway.
>
> And keeping this information in one place would also save us from having
> to more or less duplicate plenty of screen shots  (which sooner or later
> have to be updated).
>
> What do others think?
>
> Sincerely,
>   Rainer
>
> 
> --
> ___
> Qlandkartegt-users mailing list
> Qlandkartegt-users@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users
>
--
___
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users

[Qlandkartegt-users] What should be contained in the FAQ?

[Dr Rainer Woitok]

Greetings,

since about mid of August  Wolfgang has collected  a wealth of informat-
ion, tips, tricks regarding QMapShack  and put it into the various "Doc-
Faq*.md" files.

But is the FAQ the right place for ANY kind of information?   I mean, we
could put everything into the FAQ: how to download QMapShack, how to in-
stall it, how to report a bug, how to write documentation.   But I don't
think that's what a FAQ is made for.  The four topics mentioned just ab-
ove clearly should go  into the regular documentation,  and in fact they
do, as far as the QMapShack documentation is concerned.

To explain more precisely what I'm up to let's take file "DocFaqHandling
.md" as an example:  the various tricks to find distances between points
probably belong in the FAQ (even though I think QMapShack should provide
an easy to use  tool to measure  the distance between  two points rather
than requiring creation, projection, and deletion of a waypoint) whereas
information about selecting a range within a track should -- in my opin-
ion -- be contained in file "DocGisItemsTrk2.md",  where most users most
probably would expect it anyway.

And keeping this information in one place would also save us from having
to more or less duplicate plenty of screen shots  (which sooner or later
have to be updated).

What do others think?

Sincerely,
  Rainer

--
___
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users