Documentation hub/Brainstorming session

This is brainstorming

Why
Much of the functionality of SMW is undocumented on this site. Probably because the community is not editing this site.

Why is 2.3.0 undocumented?

 * Specifically much of (or most of?) the documentation on this site is out of date.
 * The examples are 7 years old.
 * Overview seems difficult.

Do we have examples/things on the wiki which are documented well?

 * configuration parameters
 * some result formats (mostly SMW core, some SRF), still examples missing

Why don't we manage to communicate of this wiki?

 * What about #Slack? Or an Open Source alternative (needs hosting, though): Mattermost

Goals
We don't practice what we preach! Lets use site!


 * 1) Make smw.org a showcase of the software itself. The BEST SHOWCASE.
 * 2) Make it easy to contribute (to the site, the documentation).
 * 3) Use the user manual as the main starting point for documentation.
 * 4) Centralize (hierarchy!) communication channels: IRC, Phabricator, GitHub, mailing list, Community portal, wiki, etc.
 * 5) Communication vs. documentation

How to get there
How do we get the community to start documenting SMW on this site (as they should do!)

Functionality – Benefit – Recognition

Help:Getting started
See cppoon.wordpress.com

Examples
The best way to explain is going from concrete to abstract. A Concrete real world Example is mostly best to understand. Quite a few examples in this wiki are currently "artificial". If we use the topics and concepts that this Wiki focuses on e.g. the Talks, Conferences and Speakers and the like as examples things will be better understandable.

Example conference agenda
A first starting point could be the beautiful conference templates. There should be a link on top of the SMWCon_Fall_2015/Conference_Days article --> learn how to make your own conference agenda. Ideally this would link to a template called "template:conferenceAgenda" which lists and explains all the containing templates that assemble the agenda

Abstract Explanation

 * 1) An ask Query first needs a selection in this example Has speaker::Yaron Koren selects a single speaker.
 * 2) The first column would normally show a link to resulting pages (in this case talks) - we give it a modified headline with a tool-tip  that is displayed as
 * 3) Then the columns are selected in this case conference, title and description. The corresponding properties are,  and
 * 4) We limit the number of results to just three with limit=3
 * 5) We use the  template as a helper Template which simplifies the syntax for Links

Example Ask Query for Special Properties
see

Gamification

 * Simple tables of what's covered in the wiki to motivate contribution and to highlight what needs to be documented.
 * Lets establish a very basic framework (now), and invite the mailing list to contribute.

Focus on main issues

 * The main issues of the community should be discussed!
 * Feedback on what functionality of SMW needs better documentation.
 * There is a survey form, which already asks for many things.
 * Results?
 * Presumably we can just query the results.

Thanks

 * Thanks extension
 * Best thing for MW since sliced bread.
 * How do we get it installed? – "Thanks requires the Echo extension be installed as a prerequisite." Installing an extension needs (at least!) approval from Karsten and/or the administrators. More info, a proposal, an evaluation etc. will surely help.

Ratings
Is the documentation rated?
 * NO
 * Lets have a 3 level rating, good, bad, or OK.
 * Or, "Was this page helpful? Yes/No" and if "No" > "How could we improve it?"
 * This will feed into the hub to guide contributors and exemplify good docs.
 * There is an extension to do that edit revs or so.
 * (There was a discussion about this already somewhere, but where?)

Best Practices and Tips

 * Tips shall be featured better

Looks
Prettify SMW.org! e.g. the infoboxes have recently been prettified, but now do not fit anymore to the overall look of the page, see example here. > There is a need for a simple, nice style guide, including fonts, colours, borders, boxes, tables etc.

WikiEditor
On smw.org there is no editor installed at the moment. Maybe the simple WikiEditor, which is doing a good job, could help?

Translate extension
The Translate extension should ease translating the site content. The software MediaWiki is translated via translatewiki.net, which is using the same extension. At the moment, site translation is done by hand by a few single translators, which is very time-consuming. To reach a broader audience, translation of content could be an important feature.

Advantages: Possible barriers: Roadmap:
 * Translation is possible into virtually any language
 * Translation via little text chunks, not entire pages
 * Changes to the original page result in the translations being moved to "Outdated", translators can check if the translation is still valid.
 * Documentation to help with understanding certain translation packages can be added.
 * Nice interface
 * Template translation (e.g. infoboxes) is only possible with Lua/Scribunto
 * Current translations cannot be lost
 * Translation is best to be done from good source text, hence, the original English text should be of high quality and easy to understand.
 * Using a consistent vocabulary throughout all languages, what words should not get translated?
 * Note down process for implementing the new feature
 * Find barriers and ways to deal with them (e.g. an expert for Lua/Scribunto, SMWCon Fall 2014!)
 * Admin to assist (for the extension installation, the settings and styling)

What is the process for trying to improve things

 * Lets establish a very basic framework (now), and invite the mailing list to ontribute.


 * Brainstorming first
 * Decision of framework (some system of encouraging contribution) first
 * This is the process:

How will this process (brainstorming included) work.
 * 1) Brainstorm
 * 2) Go home
 * 3) Continue brainstorming
 * 4) Evaluate brainstorming outcome
 * 5) Transclude brainstorming session onto the documentation hub
 * 6) Discuss in a small group about the brainstorming
 * 7) Finalize discussion by December 1st.
 * 8) Assign tasks.

We need to have multiple brainstorming sessions from different communities to identify what's missing.

Actions
To be done by December 1st


 * We need a list of specific tasks
 * We need to assign tasks to people and set deadlines


 * Review the mailing list, and look out for FAQ.
 * Identify the main areas where documentation needs improvement.
 * Identify the main topics where documentation is entirely missing.