I think this article will scare most users away rather than encouraging them 
to contribute.

You might like commad lines, tools like Hg or make. But most users prefere an 
easy start with a GUI. Nor do most Windows and OS X users really have a 
relation 
to the command line. 

The online editor has several advantages for a rookie. It supports everything 
that 
is supported by Bitbucket. If you change pages online the change is anounced on 
the overview page (via Hg it's not). You can preview the page. You can even add 
a 
commit comment. (But I doubt many will do. I am ok with using TortoiseHg to 
check the changes.) And it will keep away all the details about UTF-8, file 
extensions etc. This will help a rookie a lot.

Therefore an encouraging tutorial would start with an easy to follow example 
on how to start a page on the playground.

Next the user should learn what part of the pages is automated text. Make it 
graphic with an example, highlighting the text that will be added later on. At 
this 
point the user must not know about the details how to add the header and 
footer. 
The only thing important is: Skip them!

Now the user should know how to add and reference images. And where to place 
them. This should be done via the existing online GUI. 

Also important are the rules for the links. Simply give a practical example for 
an 
external link, a wiki internal link and a document internal link, that actually 
works in 
the playground. 

The next section would be a short howto on what to do when moving a file from 
the playgound to the correct location: How to fix the links, how to move the 
file, 
how to use your scripts.

Now it's time to describe offline editing in detail and it's pitfalls. 

And finally how to start with your scripts and the details about them.

 Always keep in mind: Just because users are not computer experts they can 
still 
write usefull documentation. Therfore try to reach these users without forcing 
a 
bunch of commad line tools on them right on the spot. If they start to become 
serious Wiki contributors they will ask for offline editing and the scripts on 
their 
own soon enough. So it's important to have all this information you gathered. 
But 
do not start it with a sentence like: 

"*Most important:* You should have sufficient knowledge of the /Markdown/ 
language!"

This is probably the point where you have lost 99% of the audience. And the 
rest 
will be scared away by the many details right before they find out how to start 
with 
the basics.

Just my 2 cents

Oliver



Am Donnerstag, 22. September 2016, 19:22:52 schrieb Dr Rainer Woitok:
> Greetings,
> 
> long time ago Oliver suggested to convert  file "README.txt" to Markdown
> because else it is not available to people reading the documentation on-
> line.  The results of my efforts are files "OfflineDocumentation.md" and
> "playground/DevelopingDocumentation.md".
> 
> The latter file is located in sub-directory "playground/" (and is reach-
> able via "DocPlayground.md") because it contains a section about editing
> an existing file online.  I would like to ask those who routinely do on-
> line editing in the wiki and thus know exactly how to do it  to put some
> meat to the bones I outlined in this section.
> 
> When this is done I will move the file from the playground to the normal
> wiki.
> 
> 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

Reply via email to