Modern Documentation Platform: docs.secondlife.com | Voters

Modern Documentation Platform: docs.secondlife.com

planned

Signal Linden

Problem

The current Second Life documentation ecosystem has several critical issues:

Content Management

MediaWiki markup creates an onerous authoring process that discourages contributions
Documentation frequently becomes outdated when new LSL functionality is introduced
Legacy content including outdated meeting notes clutters the user experience
Knowledge base and MediaWiki exist as separate, fragmented systems

Technical Infrastructure

Self-hosted MediaWiki requires ongoing maintenance and resources
Platform struggles with spam and needs extensive moderation

Solution

Build a modern, unified documentation platform at docs.secondlife.com using services like readme.com or Mintlify.

Key Features

Consolidate knowledge base and MediaWiki into a single site with proper syntax highlighting
Auto-generate LSL documentation from the upcoming open-source
lsl_definitions.yaml
file
Enable community contributions with modern editing workflows
Automatically keep documentation current with new functionality

Benefits

Eliminates self-hosting maintenance overhead
Reduces moderation burden through improved platform tooling
Transforms documentation into a dynamic, community-driven resource that scales with Second Life's development

July 2, 2025

Nexii Malthus

I am somewhat torn about the idea of consolidating into a single site or platform.
This is because I see each domain, as in Domain Knowledge
, requiring their own slight tweaks, permissions/roles, and ownership.
I think what is actually truly important is to have a coordinated or cohesive experience
 than about the technical details of being hosted in a single site / platform. They just need to have a synchronised primary navigation and just enough resemblance/common structure to connect them.

Nexii Malthus

These are the knowledge domains from what I can see:

Knowledge Domains

Official Information

SL knowledge base, articles, policies, ...

Owned by LL (with approved resident contributions)
Guides, how to use SL
Features, what you can do in/with SL
Policies, the non-legalese documents that tell residents in plain english what you are or aren't allowed to do
Support, troubleshooting and getting help

Resident knowledge

Owned by communities or individuals
Communities & nichés (Aviation, Sailing, Racing, Combat / SLMC, GTFO, RLV, ...)

Technical knowledge

Owned by champions in the field
Content Creation (Building, Meshes, Textures, Fashion, Architecture / Level Design, etc)
Scripting (LSL, SLua)

By separating knowledge domains into their own sub-sites it is actually possible to better coordinate contribution efforts and permission gradation. For example it makes sense for official information, especially policies, to be held to a carefully monitored standard due to implications affecting all residents than niché documentation of a bespoke product owned by a brand store.

Nexii Malthus

So to match the OP's post structure:
Problem
The current Second Life documentation ecosystem has several critical issues:
Content Management
Lack of final decision makers / ownership of knowledge domains / champions (previously Strife Onizuka!) / maintainers / chief editors 
Contributions are heavily locked down -- requiring an awkward request for edit rights
No staging/drafting environment
No safe/uninterrupted way to propose or test significant changes (such as to core templates affecting hundreds of pages)
Modern user/technical documentation has evolved -- modernise the markup and templating (Markdown / Markdoc / MDX)
Overwhelming Legacy Content
Wiki can't fully support complete SLua documentation that will be needed
Developers expect dev docs quality
Unable to propose and implement styling and functionality changes to the documentation website
Unable for contributors to just fix the website themselves, as it is not an opensource project
Docs need to be updated to be on par with the best docs in the field
Knowledge Base seriously needs an upgrade -- the articles are great but navigation is awful
Docs can become outdated -- an eternal problem, but can be solved by archiving legacy content and having active maintainers
Technical Infrastructure
Self-hosted MediaWiki lacks a dedicated system administrator.
Websites that require an active server/hosting (PHP / Platforms) will always be suboptimal (reliability, performance, etc) compared to lightweight statically-generated websites being served straight from a CDN / edge / offline-first cache.
Relaxed/improved flow of registrations for Second Life has had unintended side effects of spam from bots hunting for mediawikis -- which led to editing being locked down by LL. However wikis rely on soft security -- so this breaks the inherent design / fundamental operating principle of a wiki.

Nexii Malthus

Solution
Build a modern, unified documentation platform that is spread across knowledge domains where ownership & maintainers are made clear.
Use a content-driven web framework like Astro's Starlight (https://starlight.astro.build/).
Residents should have a starter project they can fork to create high-quality Second Life documentation.
Official Docs from docs.secondlife.com and should live under the Second Life github organisation (or new Second Life Docs org)
LL could approve Technical Docs projects (LSL, SLua, Content Creation, etc) to be integrated into github org. Projects under the github org would enjoy benefit of being linked together with a unified/shared primary site navigation component (via a sub-repo). Effectively feeling like part of a single site for visitors without burden on the maintainers of affecting other projects.
Community Docs projects (Aviation, Sailing, GTFO, SLMC, etc) could be approved for integration into the github org as well (and thus be accessible through docs.secondlife.com), or LL could keep a safe boundary.
Resident Docs projects (Services, Products, Brand Stores, Local Communities, etc) can run completely independently without creating a legacy content problem but enjoy a minimalistic/starter version of the high quality framework setup used by the official/community docs.
No cookie consent banners! Traveling between the docs projects hosted across different hosting & domain names MUST
 be without friction to work cohesively. If you really
 need analytics then use GDPR/CPPA/privacy-friendly analytics like Fathom or Plausible which both do not impose requiring cookie consent banners.
Key Features
Modern workflows of community contributions as opensource projects on GitHub
Use lsl_definitions.yaml
 file for LSL documentation as an official source of truth to aid in generating stub pages (new features/events/constants), updating existing pages, better taxonomies, structure and navigation
Ownership of documentation in respective fields
Maintainers have decision making powers over their docs project
Benefits
Eliminates self-hosting overhead (static websites can be hosted everywhere
)
Modern web framework aimed at content-heavy websites
Transform documentation into dynamic, community-driven resources that scale with Second Life
Communities can truly focus on their community and owning those docs
Residents can document their services, products, brands and stores freely

Kalms Resident

I am cool with it as long as we don’t lose good informations already posted. It’s extremely important that people have an easy way to learn about SL’s mechanics.

BluesToday Resident

I'm a major fan of docs, but I'm not a fan of this proposal.
When the knowledge base was moved to Invision Community in 2009, it fragmented the docs rather than improve things (else you wouldn't be talking about consolidating them now).
A project like this is likely a significant cost in labor, & the outcome is usually worse due to fragmentation.
Some responses to Signal's post:
MediaWiki markup creates an onerous authoring process
Both replacement services use MDX, which is basically the same as the markup used by MediaWiki, plus MDX would like you to know JSX to use it effectively. This might be fine for a dev team, but not for casual or even power users with no programming experience.
As all 3 solutions use basically the same markup, why only MediaWiki is considered onerous escapes me.
All 3 platforms support web browser based WYSIWYG editing that for (at least casual) users avoids having to deal directly with markup.
Neither replacement service provides a good templating system. From experience, I know templating leads to consistently formatted docs (especially API docs), & nothing else does.
Documentation frequently becomes outdated when new LSL functionality is introduced
This is not a MediaWiki problem, this is a tool chain problem.  You have the input (lsl_definitions.yaml), you need to write the solution for any platform, new or existing.
Legacy content clutters the site
Not a MediaWiki problem, you'd have to identify legacy content & exclude it in a port.
Knowledge base & MediaWiki exist as separate systems
See my opening comments.
Self hosted MediaWiki requires ongoing maintenance & resources
Are these costs greater than the ongoing SaaS cost? I see one action in the recent changes from a Linden in the last 30 days, not a lot of maintenance & resources from the Lab. Obviously, there may be costs I don't see, but admining MediaWiki is easy
.
Platform struggles with spam & needs extensive moderation
I've certainly not seen a recent change to the wiki that could be classified as either spam or moderation.
In summary
, I see no change to the authoring process. & with the loss of templating, less consistency in resulting articles. Casual users will use the WYSIWYG interface, & advanced users will deal with markup in all 3 solutions.
The other points must be addressed in the case of switching to another platform or staying with MediaWiki, or appear to be non-existent.

Peter Stindberg

To address some of your premises:

The MediaWiki authoring process acts as a gatekeeper with the DOWNside of fewer contributions, but the UPside of high quality contributions
I check the wiki daily (recent additions) and haven't noticed any amount of spam
On the other hand, a system with an easier authoring process makes spamming more easy as well

I can't comment on the self hosting overhead. It's been decades since I self-hosted a MediaWiki. Check Gwyneth Llewelyn long contribution on the forum for that matter - she seems to have extensive experience with that.

Wulfie Reanimator

I'm a contributor on the wiki (primarily LSL pages) and yes, moving to a different platform might be a good idea. I would rather go for Mintlify since it can be self-hosted.

A major problem with the existing wiki is the template-nesting-spaghetti (many of which were created almost 20 years ago) that I wouldn't want to poke much to avoid explosions. Sure, they're are useful for including the same info on many pages, but they're very complex to find/edit.

Extrude Ragu

This would be nice. Although if it is third party hosted, make sure you're keeping backups just in case. SL Tends to outlive other platforms:)

Signal Linden

Merged in a post:

Overhaul the SL Wiki Pages and Allow Contributions

RestrainedRaptor Resident

Currently, a huge portion of the SL Wiki (especially the LSL documentation) is out of date or contains wrong information. There are also dozens of example LSL scripts that are ancient, not using current best practises and should be removed.
Additionally, there are thousands of links to the old JIRA which can no longer be accessed.
Even worse, residents don't have the ability to edit pages or even contribute to the Talk pages, meaning it's impossible to make/suggest corrections (which begs the question, why are we even using a wiki system and why can we log into it with our SL accounts? Are there some special non-staff users that have this privilege?)
Perhaps LL can allocate one or two employees to go through these pages and update them, consulting with relevant developers where necessary to ensure the info is accurate. Finally, allow residents to contribute to edits and discussion (Talk pages at the very least). If that's too risky, consider recruiting more wiki volunteers.
Update: I've just found out that the contents of the old Jira have been ported to https://github.com/secondlife/jira-archive so an automated Wiki script could potentially update a lot of these old links.

July 2, 2025

Signal Linden

marked this post as

planned

SL Feedback

Merged in a post from Signal Linden:

Title: Modern Documentation Platform: docs.secondlife.com

Details: # Problem

The current Second Life documentation ecosystem has several critical issues:

Content Management

MediaWiki markup creates an onerous authoring process that discourages contributions
Documentation frequently becomes outdated when new LSL functionality is introduced
Legacy content including outdated meeting notes clutters the user experience
Knowledge base and MediaWiki exist as separate, fragmented systems

Technical Infrastructure

Self-hosted MediaWiki requires ongoing maintenance and resources
Platform struggles with spam and needs extensive moderation

Solution

Build a modern, unified documentation platform at docs.secondlife.com using services like readme.com or Mintlify.

Key Features

Consolidate knowledge base and MediaWiki into a single site with proper syntax highlighting
Auto-generate LSL documentation from the upcoming open-source
lsl_definitions.yaml
file
Enable community contributions with modern editing workflows
Automatically keep documentation current with new functionality

Benefits

Eliminates self-hosting maintenance overhead
Reduces moderation burden through improved platform tooling
Transforms documentation into a dynamic, community-driven resource that scales with Second Life's development

Peter Stindberg

Everyone
 can get write access by filing a support ticket ticket and asking for it.
If you check https://wiki.secondlife.com/wiki/Special:RecentChanges you see that the wiki is very actively maintained both by LL staff as well as by a host of resident volunteers.
You are more than welcome to join and do your own contributions.

RestrainedRaptor Resident

Peter Stindberg Good to know... Ironically, the wiki itself has inaccurate info, stating that anyone can contribute. https://wiki.secondlife.com/wiki/Project:About#How_to_contribute_to_the_wiki

Sadly I don't think I'll have the time and energy needed to make the thousands of revisions needed across the LSL wiki. That's something a paid employee should be doing.

Peter Stindberg

RestrainedRaptor Resident Yes, and sadly that page is protected and can't be edited (by me).

Noone expects you to do thousands of edits. Even if you only do a single one, it's one more than was there before.

Spidey Linden

Peter Stindberg: You are correct, thank you for adding this info!

animats Resident

Peter Stindberg I'm reasonably happy with the wiki. Much SL history and technology is in there. When, as with the JIRA to Canny transition, history is lost or forgotten, that will be a significant loss.

"readme.com"'s terms of service allow spamming users with newsletters and questionnaires. (Ref: https://readme.com/privacy#sharing-your-personal-information) And it has ads.

→