View source for History:Documentation Release

From MusicBrainz Wiki

← History:Documentation Release

You do not have permission to edit this page, for the following reason:

---

You can view and copy the source of this page.

==Abstract== [[MusicBrainz]] documentation is based almost entirely on its wiki content. This is a big strength (as it lets any editor enhance it in a collaborative fashion), but it also has a number of heavy shortcomings: * there is no clear delimitation between the (site) end-user documentation, and the "wild" wiki where long discussions, history and various propositions are intertwingled, making it rather indigest and intimidating for the newcomer * the documentation suffers from severe quality, style, and synchronization discrepancies * being the need to "lock" some content (on the [[MusicBrainz]] site side), we have a transclusion mechanism in place. Unfortunately, this mechanism is rather awkward and it's rather difficult for a handful of editors to maintain the transclusion table up to date for vastly heterogeneous contents ==Objective== We plan on incrementally enhancing the documentation ''global'' quality and try address these shortcomings, by making "micro-releases" of it. Ultimately (medium/long term?), the concept of documentation releases should be used to keep the documentation in synch with the site, and make global DocumentationRelease<code><nowiki></nowiki></code>s each time the site is updated. Also, we would like to refine our concepts about documentation, and encourage the creation of a (constant) documentation effort through the constitution of a [[Documentation Team|DocumentationTeam]] (topic which is related with the need for more [[Transclusion Editor|TransclusionEditor]]<code><nowiki></nowiki></code>s if that mechanism is going to be massively used). ==Difficulties== * no one actively worked on this, though the idea was in the air for almost one year (pretty much since the parallel emergence of the [[Wiki Wardening|WikiWardening]] effort), and despite numerous rants about the low quality of the docs, including from rather "veteran" editors * the task is '''huge''' * such an effort requires editors to switch their routine focuses: usually, people are (just) motivated to defend their ideas, and write new content to promote them. They also have strong opinions about specific points (this is fair!), areas in which they feel they are specialists while disregarding the rest (fair also!), and tendency to favor the more refined/complicated areas (being the most interesting!), not to mention ''discussing'' about things is often favored over actually documenting them ;) . Actively working on the documentation on the other hand requires to rather focus on: ** fairness about the various opinions on touchy topics ** good global experience and global view of the project and wiki ** non-tainted (eg: by a specific view on music) attitude ** ability to present content in a simple enough manner while still retaining all relevant information ** ability to just go over the usual styleML nitpicking about trivial details and purists views ** capacity to take fire for all the (potentially bold) moves you'll be forced to make (you ''will'' break some eggs - and some people ''will'' be unhappy about what you will do - including private niceties and public slandering :-) ) ** desire to do very ungrateful maintenance work Typically, this effort does not consist (essentially) in solving the various pending style issues with a brand shiny new (born-dead, most time) (possibly overkill) proposition, but rather address the problems pertaining to ''the way we document things''. ==Releases== The current target is [[Documentation Release/1.0|version 1.0]] (codenamed "Pass the Cheese, Baby" - and no, we don't need a wiki page by that name :-) ). It doesn't have to be perfect. It doesn't even have to be complete. The main purpose of it is rather to try and see if a new dynamic can be put into motion, and if we can put in place a usable and decent architecture through the use of cards. Also, eliminating the biggest zones of bit-roting and moving out the most invading discussions and history bits is one of its main objectives. ==How to Help== Unfortunately, energy and time are too sparse to devote (yet - that is, for the 1.0 release) on a well defined "newcomer" what-to-do guide. If you're a veteran [[WikiZen]] and are in the mood for it (see the "difficulties" section for a quick check), you ''know'' what to do (or you'll figure out quickly). If you don't, you can still help! You may either mail one of the editors involved in this (check the contributors to the [[Documentation Release/1.0|version 1.0]] page) for a quick heads-up, or check directly [[Documentation Release/1.0|version 1.0]] and the pages already considered "decent" and try to make some sense out of it to figure out what needs to be done. ==Notes== For additional ramblings about documentation, check [[User:dmppanda/DocumentationRelease|this page]]. [[Category:To Be Reviewed]] [[Category:Wiki]]

Return to History:Documentation Release.