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 > [email protected] > https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users
------------------------------------------------------------------------------
_______________________________________________ Qlandkartegt-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users
