[mb-style] Open request for documentation review; ReleaseTerminology
Hi all As mentioned in the other thread, I've spent some time cleaning the information in the wiki surrounding Release Terminology and the ReleaseNavigation card. This includes: - adding card navigation headers - moving discussions off page - adding basic definitions where missing - partly formalising English content of pages - intertwingling with Style pages where I can - readying for transclusion into WikiDocs Can those with some time have a quick scan through the links off http://wiki.musicbrainz.org/Cards/ReleaseNavigation and let me know of any inconsistencies (or fix them yourself!). I've been focusing on the ReleaseEvents line at the mo. In particular, I wrote http://wiki.musicbrainz.org/ReleaseDate from scratch, and as this is somewhat topical, I'd appreciate comments on it or enhancements to the page. The aim is to be relatively objective/factual in the terminology pages - style and policy is a separate issue and separate set of documentation. Chad / voice -- Ist Ihr Browser Vista-kompatibel? Jetzt die neuesten Browser-Versionen downloaden: http://www.gmx.net/de/go/browser ___ Musicbrainz-style mailing list Musicbrainz-style@lists.musicbrainz.org http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Re: [mb-style] Looking for a new [Documentation|Style] leader
> I agree with everything you've said -- I think you're certainly on the > right track. I'm ready to declare Jim as the new style leader? Does > anyone have any objections? If so, speak up now! I also completely agree with most of Jim's points as well; well thought out, well written and even better if the ideas become well executed :D On the Documentation side; somewhat dear to my heart: > > 1. There's lots of purely editorial flaws, not policy-related, in > > our docs. > > Clearly stale content labelled as under revision. Poorly structured > > pages. > > Discussion placed inconsistently within policy pages, or on separate > > Discussion pages. Unclear writing. I think we need a way to identify > > editorial problems, and open them up to low-overhead fixes that > > don't go > > through the mb-style discussion process. We need editorial > > guidelines for > > this. Newbie editors (as I was a few months ago) should be able to > > dive in > > and help with this. > > Also agreed. I think this is part of a larger problem -- our overall > docs are in disarray and could benefit from someone taking an active > role as Documentation Chief and cleaning house a bit. We've also lost > some WikiWardens who were directly involved in writing documentation, > which makes this situation worse. A WikiWarden armed with transclusion > rights would be in a good position to clean house here. > > Would anyone be interested in taking an active role in documentation > for MusicBrainz? Due to my new privilege as a TransclusionEditor I am somewhat keen to take some role in tidying this up. I am happy to be one of the "doers", but am a bit unsure about the delegation aspects - it presumes that there are people out there to delegate to, but I'm not sure many are interested in documentation these days! I am currently trying to determine the status of, and follow up on the work begun (and largely completed to a state of 1.0 readiness) by dmppanda and murdos and finish tidying (at least for a 1.0 release) the basic terminology and definitions pages using the Cards headers and footers. I will write a separate email asking for feedback and fixes on some of those I've recently been doing. Previously, I have avoided editing documentation due to the quagmire that is the approval and RFC/RFV process and what seems like differing opinions on what to do with the wiki content. I've got into it a bit more in recent months (adding missing EditTypes, fixing some Picard stuff and such) but I'd love to get a framework set up whereby I can make some serious inroads to completing the DonRedman/dmppanda/murdos work. > > > A documentation chief should/could/might: > > - Create an list of pieces of documentation that MB should have to > help its users/developers along. I wonder if http://wiki.musicbrainz.org/WantedPages is an indicator :p > - Review documentation, delete old documentation and remove > superfluous documentation. Reviewing is fine. Deleting and removing is difficult currently. Asking for community input on every individual deletion will slow this process down to zero; leaving "OLD OUTDATED" flags on documentation which is what we currently have - that's no fun. We need some general acceptance of what we want to delete/remove, a streamlined process on how we plan to delete it (announce planned page deletions in batches on mb-users?) and empower someone to JustDoIt at times. > - Identify who in the community should write/fix documentation that is > needed. > - Assign bugs to developers to fix documentation that cannot be fixed/ > written by the community at large. > - Over time, keep an eye on documentation and periodically revise > documentation as MB changes. (mostly around releases of software) > > Like the style leader, I'd hope that this person would not personally > write most of the documentation, but prod the community/volunteers/ > developers to write the documentation. > > The issue at the moment is that the problem is too big. I think we need a streamlined process for a period of time to try and clean out the bulk of the old/outdated crud so that the time can gradually be spent more on maintenance/improving/reviewing rather than restructuring/deleting/tidying. Questions I have: - How should deletion currently work? http://wiki.musicbrainz.org/CandidateForDeletion and http://wiki.musicbrainz.org/DeletedPage are currently confusing. - Having the full search macro disabled makes WikiWardening very difficult. Moreso, there are several important pages from a user perspective that rely on a FullSearch. What's the plan for re-enabling this or reducing our usage so we /can/ re-enable it? - Where is the MoinMoin upgrade stuff at? - Did we have agreement on use of the cards? And the DocumentationFooter? e.g. http://wiki.musicbrainz.org/ReleaseDate When can/should I start transcluding content that includes the cards; or has this begun already? Chad / voic
Re: [mb-style] Looking for a new style leader
On Jul 25, 2008, at 12:01 AM, Jim DeLaHunt wrote: > Everything snipped, I agreed with. > 1. There's lots of purely editorial flaws, not policy-related, in > our docs. > Clearly stale content labelled as under revision. Poorly structured > pages. > Discussion placed inconsistently within policy pages, or on separate > Discussion pages. Unclear writing. I think we need a way to identify > editorial problems, and open them up to low-overhead fixes that > don't go > through the mb-style discussion process. We need editorial > guidelines for > this. Newbie editors (as I was a few months ago) should be able to > dive in > and help with this. Also agreed. I think this is part of a larger problem -- our overall docs are in disarray and could benefit from someone taking an active role as Documentation Chief and cleaning house a bit. We've also lost some WikiWardens who were directly involved in writing documentation, which makes this situation worse. A WikiWarden armed with transclusion rights would be in a good position to clean house here. Would anyone be interested in taking an active role in documentation for MusicBrainz? A documentation chief should/could/might: - Create an list of pieces of documentation that MB should have to help its users/developers along. - Review documentation, delete old documentation and remove superfluous documentation. - Identify who in the community should write/fix documentation that is needed. - Assign bugs to developers to fix documentation that cannot be fixed/ written by the community at large. - Over time, keep an eye on documentation and periodically revise documentation as MB changes. (mostly around releases of software) Like the style leader, I'd hope that this person would not personally write most of the documentation, but prod the community/volunteers/ developers to write the documentation. > 2. For classical recordings, I think a list of common work and > movement > titles would help hugely. They would let new users copy existing > text for > TrackTitles and ReleaseTitles, without having to understand the whole > ClassicalStyleGuide. The CSGStandard pages are one approach to such > a list. > Within the last few months there was a proposal to store such a list > in the > database somehow. In either case, copying is easier than generating > anew. I need to touch base with Lukas and see how his Works branch is coming along... > 6. Our process needs some backwards arrows. There should be clear > transitions for stuck proposals to go back to an earlier stage. Do you have a rough draft that outlines how you view the process? > Interestingly, one thing which I think the Style Czar not need do > much of, > is make style policy decisions. Because, I think, we've got fine > people with > fine ideas, we already have the wisdom to get those decisions right. Once the process is properly tuned, I think this will be the case. I agree with everything you've said -- I think you're certainly on the right track. I'm ready to declare Jim as the new style leader? Does anyone have any objections? If so, speak up now! -- --ruaok Somewhere in Texas a village is *still* missing its idiot. Robert Kaye -- [EMAIL PROTECTED] --http://mayhem-chaos.net ___ Musicbrainz-style mailing list Musicbrainz-style@lists.musicbrainz.org http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
