User:Dmppanda/documentationrelease

Documentation Releases

This page

Has the short-term objective to brainztorm on how to pinpoint and address MusicBrainz' documentation problems.

It's not (yet) intended toward the casual user, doesn't go through the basics, and requires the reader to have at least a basic understanding about how the current system works (WikiDocs relation to WikiPages etc...) - though this is hardly inhuman :-) .

Abstract

While the use of transclusion and the massive wikification of both site "static" pages and "documentation" are certainly good things, this poses a number of new challenges and has a number of shortcomings.

The purpose of this document is to list and formalize these issues, propose practical solutions, and maintain working tasks list/status to have the former solved and the later implemented.

The documentation effort is (at least) partly related to the WikiWardening effort, though it has different objectives, different problems, different priorities, and may not involve the same people.

Documentation specific tasks actually listed in WikiWardening should be migrated here.

Documentation problems

... from a newcomer point-of-vue

Problems:

1. it's not clear where is the documentation - /doc ? wiki. ? and why there exists two versions of it
   • even a TransclusionEditor was spotted confused about what Transclusion was for, confusing "being transcluded" and "being official"

1. it's not clear how to access (something in) /doc, or how to find something there:
   • there is no documentation "home"
   • there is no documentation "index" (some people have been using WantedPages for that!!!)
   • there is no direct and obvious link to the documentation in the top link bar
   • /doc and /doc/ are both unusable
   • /doc/WHATEVERBOGUS doesn't show anything useful / doesn't redirect to something useful

1. it's not clear what is the documentation: for the newcomer, there is a gigantic blurb of 1000+ pages with personal pages, outdated stuff, experimental proposals, altogether mixed with terminology pages
2. the documentation is *not* visually attractive

Consequences for the newcomer:

• confusion
• reluctance to consult the documentation
• increased difficulty to get involved in the documentation enhancement effort

Documentation mis-quality

... from a WikiZen point-of-vue

Problems:

1. there's no clear definition of what should be the documentation
2. the enhancements efforts not being coordinated/planned:
   • there are (huge) content quality discrepancies between pages
   • some content are just bitroting, mostly abandoned
   • there are no timely updates of the documentation (eg: with the introduction of new features): or more accurately, it's left to the proposer of the enhancement to make/update the doc whenever he wants/can do it...

1. there are "style" discrepancies (breadcrumbing, use of formating, etc)
2. nothing is done to promote documentation editing (errrr as a "noble" task :-) )

Conflicting purposes and intents

Wiki and Documentation are two different beasts, with different needs, different life cycles, different structures.

To some extent, there is (a) conflict(s).

A good documentation has the following priorities:

• be clean
• be easily readable
• be visually attractive
• be not overwhelming (or: be concise and to the point)
• be easily browsable
• be synchronized
• be consistent
• be long-lived
• be strictly structured
• be updated incrementally and as a whole
• don't (directly) present open reflexions, random questioning
• doesn't have to be "historicized"
• be translated
• should not be modified aggressively

On the other hand, a wiki has other priorities:

• be wild and living
• encourage inline discussion
• should constantly transform itself, including its structure, its organization
• emphasize the preservation, recycling, and possibly "slow degradation/digestion" of "historical" content
• encourage the proliferation of new ideas and new propositions

and doesn't have a need for most of Documentation's priorities:

• (probably) doesn't have to be translated
• doesn't need to be consistent, "newbie-easy-browsable", synchronized etc

To some extent, DonRedman vision of an ecosystem is an accurate description of what a wiki should be. On the other hand, a Documentation is better seen as a unique consistent mechanical entity, like a... I don't know... a smoking-moose? :D

Fact is, our documentation is mostly also our wiki. I don't see this as a formal and impossible to solve contradiction. Actually, and more accurately, our wiki (as in "our wiki content") and our documentation are commonly hosted and managed on a wiki (as in "content management tool").

There is IMO no need to change that, and this tool is adequate for both: what is lacking is a different methodology for two different things.

Most of our current "methodology tools" (eg: WikiTags, Categories, flat hierarchy, WantedPages, etc) are either not adequate to serve documentation goals, or too primitive to coordinate documentation efforts.

Furthermore, to have different methodologies, we first need to define where is the limit between the two.

Some random notes

http://musicbrainz.org/show/edit/?editid=6820055

Ideas to solve the mess

Random notes:

terminology but not style

either drop transclusion for most wiki content (but "static" information pages), either enhance it and promote its use (Don proposal) and extend it to *all* the documentation

don't overuse release structuring

add site loadable stylesheets transparently applied only on /doc

add javascript snippet (table sorting / navbar hiding)

coordinate documentation editing using release

make release plans with objective

synchronize doc releases with server releases

use documentations zone.