WikiDocs: Difference between revisions
From MusicBrainz Wiki
Jump to navigationJump to search
PavanChander (talk | contribs) (Condensed & simplified; only relevant content kept.) |
Silentbird (talk | contribs) m (simplify language) |
||
| (18 intermediate revisions by 7 users not shown) | |||
| Line 1: | Line 1: | ||
Most of MusicBrainz's documentation is located at https://wiki.musicbrainz.org/ and transcluded at https://musicbrainz.org/doc/. |
|||
| ⚫ | |||
This WikiDocs system works because: |
|||
With a few exceptions, the [[MusicBrainz Wiki]] is the source of all MusicBrainz' documentation. |
|||
# It leaves the wiki (and by extension, the documentation) open for mass collaboration. |
|||
| ⚫ | |||
| ⚫ | |||
This is achieved by transcluding all the content from http://wiki.musicbrainz.org/ to http://musicbrainz.org/doc/. |
|||
| ⚫ | |||
The structure of the WikiDocs system looks like this: |
|||
# The content resides in the wiki, and anyone can edit and maintain it. |
|||
# [[Transclusion Editor|Transclusion editor]]s add and update entries in the [[mb:admin/wikidoc|transclusion table]] for official documentation pages. |
|||
| ⚫ | |||
# Users visiting that same page on the main website will be shown, via transclusion, only the latest reviewed revision of that page. |
|||
Pages served via transclusion cannot be edited on the website. |
|||
The MusicBrainz Wiki is seen as the community responsible for generating all the documentation, help pages, and guidelines for MusicBrainz. The wiki community has been very efficient in doing this because both the experts (the solution providers) ''and'' the non-experts (the question posers) collaborate in the same space. |
|||
==How To Transclude a WikiDocs Page== |
|||
Thus, it is vitally important for the wiki to be open for anyone to edit. |
|||
'''Only transclusion editors can do this.''' |
|||
Leaving the wiki open anyone to edit has its inconveniences though. There are various pages that have had their content carefully written by the consensus of the Musicbrainz user community (such as the [[Frequently Asked Questions|FAQ]s] and the [[Official Style Guideline|style guidelines]) warrant an 'official' status. There are also other pages that are integrated into the main site (such as [[Products|product]], [[Development|development]], and [[MusicBrainz License|licensing]] pages) that provide visitors and new users their first impressions of MusicBrainz. The damage an editor on the wiki can do, whether maliciously or just by accident, is quite extensive. |
|||
: [[Image:Attention.png]] ''Please be very careful to enter the correct page name and revision number, because they are '''not''' checked for correctness.'' |
|||
Therefore the WikiDocs system was introduced that accounted for the above by: |
|||
# Leaving the wiki open for mass collaboration on http://wiki.musicbrainz.org/. |
|||
| ⚫ | |||
Go to the [[mb:admin/wikidoc|wiki transclusion table]]. Each page has its own row, which can be edited or removed. New rows can also be added. When a [[WikiDocs]] page has been edited, and the change conforms with the style guidelines and other social aspects — and most importantly, makes the documentation better — the change should be reflected on the main server. To do this, find the latest revision number using the page history and update it in the transclusion table. |
|||
== WikiDocs Structure == |
|||
| ⚫ | |||
The structure of the WikiDocs system looks like this: |
|||
# All content resides in the [[MusicBrainz Wiki]]. |
|||
# [[Transclusion Editor|Transclusion editors]] add/maintain entries on the [http://musicbrainz.org/edit/wikitransclusion/transclusion.html transclusion table] for pages that require controlled transclusion. |
|||
| ⚫ | |||
# Users visiting the MusicBrainz website will be served content from the wiki via the [[Wiki Web Service|wiki web service]] which checks to see if the page being requested exists in the transclusion table. |
|||
#* If it does, the web service will fetch the page using the revision number listed on the table, pass it through the [[WikiDocs Conversion|WikiDocs conversion]] process, and finally serve it. |
|||
#* If it doesn't, the web service fetches the current revision of the wiki page and passes it through the [[WikiDocs Conversion|WikiDocs conversion]] process, which, among other things, adds a warning that the page ''"has not been reviewed by our documentation team"'' before it's served. |
|||
When adding a new page to the table, make sure to add it to the [[:Category:WikiDocs Page|WikiDocs page]] category. |
|||
The pages served by the web service are not editable on the website, but they all provide a link back to their corresponding page on the wiki. |
|||
[[Category:Wiki]] [[Category:WikiDocs Page]] |
[[Category:Wiki]] [[Category:WikiDocs Page]] |
||
Latest revision as of 13:36, 23 January 2021
Most of MusicBrainz's documentation is located at https://wiki.musicbrainz.org/ and transcluded at https://musicbrainz.org/doc/.
This WikiDocs system works because:
- It leaves the wiki (and by extension, the documentation) open for mass collaboration.
- It lets transclusion editors control what can be seen on the main site.
WikiDocs Structure
The structure of the WikiDocs system looks like this:
- The content resides in the wiki, and anyone can edit and maintain it.
- Transclusion editors add and update entries in the transclusion table for official documentation pages.
- Users visiting a page on the wiki see no difference; they always see the most recent revision of every page.
- Users visiting that same page on the main website will be shown, via transclusion, only the latest reviewed revision of that page.
Pages served via transclusion cannot be edited on the website.
How To Transclude a WikiDocs Page
Only transclusion editors can do this.
Please be very careful to enter the correct page name and revision number, because they are not checked for correctness.
Go to the wiki transclusion table. Each page has its own row, which can be edited or removed. New rows can also be added. When a WikiDocs page has been edited, and the change conforms with the style guidelines and other social aspects — and most importantly, makes the documentation better — the change should be reflected on the main server. To do this, find the latest revision number using the page history and update it in the transclusion table.
When adding a new page to the table, make sure to add it to the WikiDocs page category.
