After my personal experience in setting up a customized Wikibase repository, I wrote a quick explanation on how to enable Direct Access using the SiteLinks.
I placed the text in the "Advanced configuration" page.

I hope this is a useful contribution and that it will be useful for other users setting Wikibase up.

Please allow me another comment after @Addshore edit above.
My personal impression with the documentation is that it is too directive without really explaining: the user is guided doing several tasks one after the other, but there is no explanation on what the user is actually doing and how this would reflect in the Wikibase operations.

For instance, as we are discussing here, the user is told to run populateSitesTable.php but nowhere is explained what the sites table contains and what sites are added via this script. If a user is setting up a custom Wikibase installation, most likely this "standard" sites are not even necessary at all.
What I tried to do adding the instructions here https://www.mediawiki.org/wiki/Wikibase/Installation/Advanced_configuration#Direct_access_and_SiteLinks was to share a procedure as much as explaining why the procedure must be done and what result the user will get eventually.

As a newcomer to Wikibase, I found the most difficult thing being not understanding the general principles of the extension, before actually make it work. For instance, again, nowhere was explained what Sitelinks are and what is their relation with the Direct Access: after I grasped the way it actually functioned, doing the configuration ended up being the easiest part.
My two cents at the end of the day, so, are: let's review the documentation first explaining the user how Wikibase works, then helping the user set it up to work like he would.

Please have a look at the draft at https://www.mediawiki.org/wiki/User:Michael_Gro%C3%9Fe_(WMDE)/WikibaseSiteLinksDoku . This draft is intended to be added to https://www.mediawiki.org/wiki/Wikibase/Installation as a same-level headline after the Verify your installation section.

Please check if

• the text is easy to understand and follow
• you consider this the right place to add it
• the text fulfills the acceptance criteria as defined above.

One thing that seems missing from the documentation is how to insert your site into sites table. That's actually hard to do manually and I never was able to do it properly. What I do is to run this type of code in eval.php

$sites = [];
$langCode = 'en';
$site = new MediaWikiSite();
$site->setGlobalId( 'clientwiki' );
$site->setGroup( 'wikipedia' );
$site->setLanguageCode( $langCode );
$site->addInterwikiId( $langCode );
$site->addNavigationId( $langCode );
$site->setPath( MediaWikiSite::PATH_PAGE, "https://redis-dispatching-client.wmflabs.org/index.php/$1" );
$site->setPath( MediaWikiSite::PATH_FILE, "https://redis-dispatching-client.wmflabs.org/$1" );
$sites[] = $site;



$sitesTable = SiteSQLStore::newInstance();
$sitesTable->clear();
$sitesTable->saveSites( $sites );

Of course you can skip the clear part if you want to keep other sites.

An almost identical example already exists at https://www.mediawiki.org/wiki/Manual:Sites_table#Managing_the_sites_table, so I made the link there much more prominent in order to not duplicate documentation. Would that work for you, @Ladsgroup?

In T218282#5112640, @Ladsgroup wrote:

One thing that seems missing from the documentation is how to insert your site into sites table. That's actually hard to do manually and I never was able to do it properly. What I do is to run this type of code in eval.php

My opinion is that the right place for those instructions is https://www.mediawiki.org/wiki/Manual:Sites_table#Managing_the_sites_table
In fact I added instructions there in order to use a manually created XML to import sites: in my experience it is by far the simpler and more versatile procedure.

In T218282#5107406, @Michael wrote:

Please have a look at the draft at https://www.mediawiki.org/wiki/User:Michael_Gro%C3%9Fe_(WMDE)/WikibaseSiteLinksDoku . This draft is intended to be added to https://www.mediawiki.org/wiki/Wikibase/Installation as a same-level headline after the Verify your installation section.

Please check if

• the text is easy to understand and follow
• you consider this the right place to add it
• the text fulfills the acceptance criteria as defined above.

Dear @Michael ,
thanks for your effort and thanks for using some of my contributions for the instructions you wrote. I reviewed your text and following please find my considerations:

• If this is the right place to add the text depends on what we consider Standard and Advanced configuration. I agree to put this specific text where you suggest to, but then I am not sure any longer if it make sense to have two separate installation instructions page, instead of one well-organized one
• The candidate documentation in my opinion fails to explain the user the concepts behind. As I wrote above, I consider this of paramount importance. The paragraph is titled Enable SiteLinks, but nowhere is explained what a "SiteLink" is or what relation has with "Direct Access". In the brief introduction I wrote, those terms were at least referenced and linked
• Are we sure that Extension:WikimediaMessages must be installed to edit messages? In my installation I was able to modify them by simply editing the page MediaWiki:Wikibase-sitelinks-yourgroupnamehere
• I would move $wgWBRepoSettings after the instructions about Sites (if not, above and below must be adapted)
• It seems to me that using Special:SetSiteLink is less user-friendly than setting the SiteLink in the related box in the item's page
• I think the wiki where Repository is installed should be referenced in a clearer way in respect to simply your wiki: as we are always talking about wikis, I am not sure it is clear to the users what is the consumer and what the consumed one

I am surely biased here – and this is the reason I would be glad to see other contributions as well – but I still find the instructions more linear and informative the way I originally wrote them. Please bear in mind that I started as an absolute beginner of Wikibase, so the documentation I wrote is the result of the process of learning how to configure Wikibase starting from scratch and formalizing Wikibase concepts by induction.

In T218282#5114203, @Michael wrote:

An almost identical example already exists at https://www.mediawiki.org/wiki/Manual:Sites_table#Managing_the_sites_table, so I made the link there much more prominent in order to not duplicate documentation. Would that work for you, @Ladsgroup?

Yes, that's a good idea. Thanks!

@lucamauri Your feedback is very welcome and helpful. Thank you!

In T218282#5114315, @lucamauri wrote:

• If this is the right place to add the text depends on what we consider Standard and Advanced configuration. I agree to put this specific text where you suggest to, but then I am not sure any longer if it make sense to have two separate installation instructions page, instead of one well-organized one

Yes, I intended to prune the other "Advanced" config to remove duplication. I suggested adding this content to the main installation page, because the Item pages feel actively broken/incomplete without it, since the sitelinks are such a large section on the Item page.

• The candidate documentation in my opinion fails to explain the user the concepts behind. As I wrote above, I consider this of paramount importance. The paragraph is titled Enable SiteLinks, but nowhere is explained what a "SiteLink" is or what relation has with "Direct Access". In the brief introduction I wrote, those terms were at least referenced and linked

Yes, some introduction is a good idea. I would like to focus here more on getting the sitelinks on the Item pages to work and have a guide about Direct Access on the advanced config page or somewhere else.

• Are we sure that Extension:WikimediaMessages must be installed to edit messages? In my installation I was able to modify them by simply editing the page MediaWiki:Wikibase-sitelinks-yourgroupnamehere

No, Extension:WikimediaMessages is only needed if one wants to use the default/example settings. Apparently, I should phrase this clearer. Or maybe drop it completely, because 3rd Party installations will likely never use it.

• I would move $wgWBRepoSettings after the instructions about Sites (if not, above and below must be adapted)

I moved it towards step 1, because I find it important to think about the desired structure in the sidebar before adding sites to the table, as changing the sites table again afterwards can be annoying. But you are right, when incorporating your lines I missed adjusting some words. Will fix :)

• It seems to me that using Special:SetSiteLink is less user-friendly than setting the SiteLink in the related box in the item's page

True, I mainly intended it as a verification step, as the SiteLink widget in the related box in the item's page can give for some problems no error message at all. However, you are very right as far as everyday usage is concerned.

• I think the wiki where Repository is installed should be referenced in a clearer way in respect to simply your wiki: as we are always talking about wikis, I am not sure it is clear to the users what is the consumer and what the consumed one

Good point, I will make this clearer.

In T218282#5114533, @Michael wrote:

@lucamauri Your feedback is very welcome and helpful. Thank you!

My pleasure if I can help any other user 😊

Yes, I intended to prune the other "Advanced" config to remove duplication. I suggested adding this content to the main installation page, because the Item pages feel actively broken/incomplete without it, since the sitelinks are such a large section on the Item page.

Surely I agree with you. May I suggest to work on the documentation on higher level? I would start from scratch writing down all the relevant topics in the config (like they are sections heading), choose if they belong to Basic or Advanced and then fill the content. To a newcomer like me, the documentation looks only partly coordinated and very often just a bunch of notes. Much of the text can and should be reused, but the structure can be improved, I think. Does in your opinion make sense to start such an effort? Maybe I can help as well with the notes I took along the way.

Yes, some introduction is a good idea. I would like to focus here more on getting the sitelinks on the Item pages to work and have a guide about Direct Access on the advanced config page or somewhere else.

To this point I must respectfully disagree as – at least in my personal experience with Wikibase – it was not easy to grasp the relations between SL and DA at first glance. If we go on with the respective guides in two separate pages, please let's have a clear hyperlink between the two

No, Extension:WikimediaMessages is only needed if one wants to use the default/example settings. Apparently, I should phrase this clearer. Or maybe drop it completely, because 3rd Party installations will likely never use it.

I would rephrase it. Can I directly contribute to the subpage in case I can think of something else?

True, I mainly intended it as a verification step, as the SiteLink widget in the related box in the item's page can give for some problems no error message at all. However, you are very right as far as everyday usage is concerned.

Now that you put like that, I see your point. In fact, using that method, maybe would have helped me as well at the beginning. Maybe we can instruct the user to try in the box and, if it does not work, to try again on that page for some troubleshooting.

In T218282#5115178, @lucamauri wrote:

May I suggest to work on the documentation on higher level? I would start from scratch writing down all the relevant topics in the config (like they are sections heading), choose if they belong to Basic or Advanced and then fill the content. To a newcomer like me, the documentation looks only partly coordinated and very often just a bunch of notes. Much of the text can and should be reused, but the structure can be improved, I think. Does in your opinion make sense to start such an effort? Maybe I can help as well with the notes I took along the way.

Rethinking the structure of the documentation sounds reasonable. However, rewriting it from scratch would certainly be a large effort. Thus, I would suggest that we get this specific piece of information merged first, so that we can point other users with that problem to it. Also, @Lydia_Pintscher is the one that decides how to move forward with the documentation and how to prioritise it with respect to our other tasks.

Yes, some introduction is a good idea. I would like to focus here more on getting the sitelinks on the Item pages to work and have a guide about Direct Access on the advanced config page or somewhere else.

To this point I must respectfully disagree as – at least in my personal experience with Wikibase – it was not easy to grasp the relations between SL and DA at first glance. If we go on with the respective guides in two separate pages, please let's have a clear hyperlink between the two

Mh, you might be right there. I added some more information about direct access to it. What do you think?

No, Extension:WikimediaMessages is only needed if one wants to use the default/example settings. Apparently, I should phrase this clearer. Or maybe drop it completely, because 3rd Party installations will likely never use it.

I would rephrase it. Can I directly contribute to the subpage in case I can think of something else?

I dropped it for now. Especially, if we also talk about direct access, then it might start to get confusing. Because, even if one sets a sitelink to a Wikipedia page, one obviously could not use direct access to link back to the custom repo-wiki. Now it should be easier to follow.

True, I mainly intended it as a verification step, as the SiteLink widget in the related box in the item's page can give for some problems no error message at all. However, you are very right as far as everyday usage is concerned.

Now that you put like that, I see your point. In fact, using that method, maybe would have helped me as well at the beginning. Maybe we can instruct the user to try in the box and, if it does not work, to try again on that page for some troubleshooting.

I added a second step to the verification section to have the user actively verify that direct access works.

Feel free to rephrase any of it if you think of something :)

In T218282#5115798, @Michael wrote:

Rethinking the structure of the documentation sounds reasonable. However, rewriting it from scratch would certainly be a large effort. Thus, I would suggest that we get this specific piece of information merged first, so that we can point other users with that problem to it. Also, @Lydia_Pintscher is the one that decides how to move forward with the documentation and how to prioritise it with respect to our other tasks.

I understood this would be a huge feat, but still worthy in my opinion because the platform will be as useful for the user as they find it easy to configure and use. But I am nobody in this project to push for anything.
Anyway, if @Lydia_Pintscher decides for a plan like this, I would surely be glad to help

Mh, you might be right there. I added some more information about direct access to it. What do you think?

I like the way you put it down, very helpful at first sight

I dropped it for now. Especially, if we also talk about direct access, then it might start to get confusing. Because, even if one sets a sitelink to a Wikipedia page, one obviously could not use direct access to link back to the custom repo-wiki. Now it should be easier to follow.

This is maybe a candidate for the Advanced page. The box is named automatically as Wikibase-sitelinks-yourgroupnamehere so it's ugly, but very understandable to the user. After the user has set the environment up, they might want to polish a little and adjust the title of the box: at that point looking in the Advanced page sounds reasonable.

Feel free to rephrase any of it if you think of something :)

I'll be a little busy today, but I'll do my best to have a closer look to it and contribute where I can 😊

Nicely done, clear and helpful. These might be relevant improvements:

• In section 2 ("Localize your own groups") there seems to be a reference annotation after MediaWiki:Wikibase-sitelinks-yourgroupnamehere. It seems not to be linked to anything.
• In section 4.1 it might be good to add a hint for the relevant field in case it's not clear from the labels, something like: "in your wiki and try to link an existing page (field Site ID) on one of the above configured sites to an existing Item (field ID). "

In T218282#5122616, @noarave wrote:

Nicely done, clear and helpful.

Thank you 🙏

• In section 2 ("Localize your own groups") there seems to be a reference annotation after MediaWiki:Wikibase-sitelinks-yourgroupnamehere. It seems not to be linked to anything.

The reference should be shown at the very bottom of the page. At least it does for me? 🤔

• In section 4.1 it might be good to add a hint for the relevant field in case it's not clear from the labels, something like: "in your wiki and try to link an existing page (field Site ID) on one of the above configured sites to an existing Item (field ID). "

Good idea! I've amended that line.

@Lydia_Pintscher and @Lea_Lacroix_WMDE please see the new documentation at https://www.mediawiki.org/wiki/Wikibase/Installation#Enable_Sitelinks and also note the corresponding removed section in the advanced config to prevent duplication: https://www.mediawiki.org/w/index.php?title=Wikibase/Installation/Advanced_configuration&type=revision&diff=3204730&oldid=3203259&diffmode=source