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.

Questions

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.
   1. 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

Example Explaining an ask Query

Concrete Query

{{#ask: [[Has speaker::Yaron Koren]]
|mainlabel=Talk {{#info:{{Link|target=SMWCon_-_Contributions|title=Other SMW Talks}}}}
|?Has conference=event
|?Has title=title
|?Has description=description
|limit=3
}}

Talk Other SMW Talks	event	title	description
"Data is data" and the future of data browsing	SMWCon Spring 2013	"Data is data" and the future of data browsing	Toward a unified theory of data browsing, and what it means for SMW's browsing functionality, including Semantic Drilldown and others.
Business Process Management (BPM) with MediaWiki	SMWCon Fall 2019	Business Process Management (BPM) with MediaWiki	Learn about a planned dedicated extension supporting BPM with MediaWiki
Cargo and Page Forms: state of the extensions	SMWCon Fall 2019	Cargo and Page Forms: state of the extensions	This talk will cover some of the recent improvements and new features in the Cargo and Page Forms extensions, and show how the two can work closely alongside one another. (Note: this talk can be split up into two if necessary.)
... further results

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 {{#info:{{Link|target=SMWCon_-_Contributions|title=Other SMW Talks}}}} that is displayed as Other SMW Talks
3. Then the columns are selected in this case conference, title and description. The corresponding properties are Property:Has conference, Property:Has title and Property:Has description
4. We limit the number of results to just three with limit=3
5. We use the Template:Link template as a helper Template which simplifies the syntax for Links

Example Ask Query for Special Properties

see SemanticMediaWiki issue 1279

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.

Possible technical improvements

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:

• 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

Possible barriers:

• 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?

Roadmap:

• 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)

Organization

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.