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.yamlfile
- 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
Log In
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.yamlfile 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.
Signal Linden
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.yamlfile
- 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.
Load More
→