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.

To some extent, this page shares with efforts documented in RestructuringTheDocumentation, WikiDocs, MusicBrainzDocumentation, HelpfulTransclusionInterface

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
   • there are also a number of confusing documents in random (?) places: http://musicbrainz.org/style.html (interestingly outdated, and not wikidocselted) or http://musicbrainz.org/doc/FrequentlyAskedQuestions accessible from "help", when http://musicbrainz.org/doc/HowEditingWorks (redirected from mod_intro) serves as an entry point for the doc

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.

Ideas to solve the mess

1. Patching mb_server:
   • move out outdated docs
     • http://musicbrainz.org/style.html
   • wikidocify remaining static pages
     • see http://wiki.musicbrainz.org/WikiDocsPage
   • fix topbar links
     • kill the redirects
     • ...
   • add a new documentation link in the topbar
   • fix urls /doc, /doc/, /doc/BOGUS so they are useful
2. Delimitate what the Documentation is. Probably, all that requires visibility on the website - be it end-user products, howtos, or anything useful to start editing, that is:
   • as a first "subproject", allthat has to do with how the site work, and the basic MB concepts, plus the EditTypes and AR pages. That may get somewhere 200-300 pages. IMO, these pages are hardly controversial, and there is no much reasons for them to sport discussions, etc - they are mainly "descriptive"
   • Products, probably, as a distinct subproject
   • Introductory MusicBrainz documentation and various other instutional docs (license, etc): not really "documentation" as we state it here, though some of the idea here could be used there
   • HowTos... probably in a second go, and maintained "separated" anyway
   • StyleGuidelines should stay out (for now), unless they are really stable and undiscussed
   • CommunityProjects has to stay out. Wiki is fit for these
   • Metadata, Development => wiki
   • EditingGuidelines... pffff... untouched for eons... lots of work on these *anyhow*
   • Wiki related stuff => wiki
3. Enhance access to/navigation inside the documentation
   • have selective style that will show/hide things depending if they are on the wiki or on the site: this is *trivial* to do with css classes, using visibility
     • breadcrumbs (panda-style-breadcrumbs) only on /doc, not in /wiki
     • "Category footer": hidden on /doc (useless in a documentation IMHO)
   • have non hierarchical breadcrumbs, giving easy access to all *relevant* documents in the current topic
   • have footers linking to additional documentation
   • tighten up and have more bridges between editing points and documentation: http://musicbrainz.org/show/edit/?editid=6820055
4. Enhance attractiveness of the documentation
   • have an additional stylesheet loaded in the site (ideally, editable by WikiZens), that will allow to enhance the /doc side without messing with the wiki side, and without having to hack mb_server
   • have a set of new iconography beyond (yet to be thought about)
   • have a "concision" motto
   • have some consistency in pages organization (paragraph titles in terminology), h1, TOCs
   • avoid CamelCase links on things that are really *fixed* (ReleaseAnnotation is not going to be renamed any time soon, hopefully). CamelCase don't make sense in a documentation IMHO
   • use screenshots!
   • add new javascript snippets (table sorting / navbar hiding), possibly for both wiki and doc (got some in my bag)
   • better explain the link between doc/wiki, and enhance the switch between doc and wiki with a big fat (not too fat :-)) wiki-logo on top of the page (even transcluded)
5. Enhance maintainability and consistency accross docs
   • have header and footer cards statements allowing to update the nav/status of a whole lot of docs at one time
   • either drop transclusion for most wiki content (but "static" information pages), either enhance it and promote its use (see Don new proposal) and extend it to *all* the "documentation"
6. Organize the documentation efforts:
   • introduce the idea of documentation releases: using Backlinks DocumentationRelease/X.Y (X.Y being a version number, and page listing objectives for that release)
   • have clear release plans with objectives
   • update transclusion table by releases
   • synchronize major releases with server releases (or the other way round) (Products obviously have its own schedule, and "static and institutional docs" possibly don't have)
   • delimitate documentation zones: new categories have been introduced lately (,, etc). When enough people are interested, we could have delegation/responsability zones (do we really need that?)
   • don't overuse that! We don't need to bureaucratize this to death. This should be kept to what it's useful for: a coordination and objective driving tool, not a coercitive procedural stuff preventing efforts
   • promote documentation editing (errrr as a "noble" task :-) ) by having some sort of honorary status for DocumentationEditors
7. Crazy idea? Have a "community validation process", to certify documentation accuracy:
   • build up a group of volunteers (don't have to be WikiZens nor AutoEditors, just random editors is the best), DocumentationReviewers
   • have these people read the documentation pages for the given release, and have them provide input on how to enhance it / state it's accurate

Crazy Ideas

• Make and distribute (from releases), a MusicBrainz downloadable documentation handbook (exported from the "printable" display, maybe transformed into pdf, chm, docbook).
• Having documentation releases structured and driven, we could bring back to life the old idea of translated documentation in a feasible way.