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 WikiPage
s 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:
- 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"
- 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
- 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
- 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:
- there's no clear definition of what should be the documentation
- 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...
- there are "style" discrepancies (breadcrumbing, use of formating, etc)
- 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.
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.