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 
to the command line. 

The online editor has several advantages for a rookie. It supports everything 
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 
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 
point the user must not know about the details how to add the header and 
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 
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 
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 
write usefull documentation. Therfore try to reach these users without forcing 
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 
own soon enough. So it's important to have all this information you gathered. 
do not start it with a sentence like: 

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

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

Just my 2 cents


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

Reply via email to