SomeReviewNotes

Introduction

  • This page contains a summary of my thoughts towards Spec/MOTUWikiCleanUp, driven in part by a review of the Wiki.

General Notes

Audience

  • Documententation should be written so as to provide clear information to four distinct groups:
  • The interested public
  • Those who will need a sponsor to accomplish the goal
  • Those who will perform the action directly
  • Those sponsoring/reviewing the actions of others

Integration with Launchpad

  • Where practicable, any guide towards doing things to support development should include documentation of the workflow using launchpad to complete the action.

Processes

  • Each process page should contain the following sections:
  • Description of the purpose of the process
  • The relevant policy governing the process
  • Procedural documentation for each distinct audience Process pages should be based on a Task focus, rather than being workflow outlines for specific teams: it's much easier to rationalise a process when all the steps are in one place.

Organisation

  • All Development-related pages should be in a clear Development namespace
  • There should be no pages that are only links to other pages - use a TOC instead
  • There should be clear separation between information about Ubuntu-specific activities and general information. Where appropriate, process pages should link to general guides, and general guides should link to relevant Ubuntu processes.
  • There should be overview pages for each development role (Contributor, Developer, Core Developer) pointing to relevant process pages, and other links of interest.

  • This section needs more thought Smile :)

Page Size

  • Small pages should be avoided, and the content rather included in a larger page, to provide the appropriate context for the reader.

Integration with Community Help

Teams

  • Team pages should include, at a minimum:
  • The name of the team
  • Activities overview for the team
  • Formal charter for the team
  • Pointer to LP team to see membership, etc.
  • Indication of criteria for team membership
  • Pointers to other pages of interest to the team Pages previously used by no-longer active teams should be archived, or merged elsewhere Separately from the above, how is a MOTU team different than other development teams?

Specs

  • New specifications should really go into a /Spec/ namespace, and the documentation and guidelines for creating these should indicate as much. This makes it much easier to separate documents of historical or future planning interest from documentation of current practice.

Wiki Wishlist

  • It would be really nice to have a simple anchor tag, so that links to headers in longer pages had a simple syntax.

Review of pages in the Wiki

  • The sections below are loosely organised as I thought of categories: they don't really mean anything other than being a way for me to organise my thoughts. This is also currently a work in progress. While I've read all the pages, I've not yet compiled all the comments.

Contributing

  • ContributeToUbuntu is a good page, but the section on contributing to Universe needs an update.

  • HelpingUbuntu is nice, and has lots of content that probably belongs in ContributeToUbuntu

  • EasyWaysToHelpUbuntu Needs cleanup, and might be better as a section in ContributeToUbuntu

  • MOTU/Contributing is over-detailed, and doesn't match the other contributing documents well. Also, there are instructions here that are useful beyond contributing (How to prepare a patch, how to prepare a new revision, how to prepare a new package).

  • ContributingToDebian could use a refresh, and update, and pointers to DCT

  • NewDevelopersAndMaintainers is confusingly named. If this must be kept for historical reasons, it should be put in /Historical/ or /Archive/. External links that break reaching this page are probably preferable to actually presenting this content as official.

  • DocumentationTeam/GettingStarted is a nice example of an introduction. Let's shoot for something with this feel.

Packaging

Patching

  • MeetingLogs/openweekfeisty/patching could use review, and extraction of good bits not covered elsewhere.

  • Bugs/HowToFix would benefit from review and better process integration (what is sought from those who can edit code, but are unfamilar with packaging?)

General

  • PackageManagement is very outdated, but has some useful bits. It probably needs pointers to a real spec

  • Pages like MozillaTeam/Bugs/Triage/Responses should be encouraged for all teams.

  • DebuggingProcedures Contains lots of links, but no guidance

  • DevelopersDocumentation is hopelessly sparse

  • Acronyms should either be expanded (and agressively linked) or dropped

  • DocumentationTeam/Ideas makes some good points, worth reviewing

  • MOTU is a nice page, but probably needs a refresh as part of the rewrite

  • LinuxTips is the least useful collection of Linux tips it has been my profound misfortune not to be able to avoid viewing.

  • MOTU/FAQ has good information, but this isn't the best place for it. Also, these don't appear t tbe the most frequently asked of questions (although maybe that's because people read the FAQ).

  • KubuntuDocs is nice, but seems lonely.

  • MOTU/Headers/Menu has a color scheme that doesn't match the default.

  • AptitudeClassroom would benefit from integration with the log to be more useful to readers.

  • UbuntuFAQ should probably be a redirect

  • Launchpad/BzrHowto should probably be a redirect

Processes

Bugs

  • Bugs/UsefulSearches seems like the best place to keep lots of searches. Those MOTU pages with bug searches might do better to be added as part of a rewrite of this page.

  • DrinkingFromTheFirehose is nice, but I haven't seen much documentation as to the resulting new processes. Is this bughelper? Does it just need more work?

  • Debian/Bugs should be emphasized: it's especially important to encourage those making new revisions, or processing merges to check to make sure the bugs are filed in Debian, and if so, are linked appropriately to the (now closed) LP bugs. Some cleanup would be nice as well, and perhaps less emphasis on reportbug, for those with broken local mail configurations.

  • Bugs/Importance Should be more visisble to Developers. As it is, those who didn't come through BugSquad (and those that have forgotten) often set Importance differently than specified here.

  • Bugs/Responses is hard to use, and now growing very large.

  • Debugging should probably be a redirect to DebuggingProcedures

  • DebuggingProcedures probably could be merged with other bug pages.

Other

  • DCT/DesktopFiles should be reconciled with MOTU/Packages/DesktopFiles, so there is a consistent policy. See also https://blueprints.launchpad.net/rosetta/+spec/rosetta-desktopfile-ui

  • IconComposition should have more informtion about preferred formats, filesystem locations, themes which are being actively developed locally, etc. Also, the .desktop file pages should link here. The link to the ArtTeam should also be updated.

  • LaunchpadHowTo Could use signifcant expansion, including notes on things for which one must belong to specific teams, etc.

  • MOTU/School should be more about school (and planning sessions, archives, etc.) and less about MOTU and contributing

  • MOTU/School/Requests needs a kick to be useful again - I don't hear enough about it

  • MOTU/TODO is a great list of resources, and a handy way to track things, and should have a place somewhere. It could also be prettified. Some of the philosophy expressed in MOTU/Contributing might be useful here. Use of real URLs is also preferred, as it makes it easier to tweak.

  • MOTU/wx2.4Migration - transitions and other package-related coordination activities are better managed as LP bugs with many tasks. A bug should but opened in LP for the issue, and affected packages added as tasks. Developers should manage the bug as they normally would.

  • KernelTeam/KnowledgeBase should be highlighted more

  • CreatingBzrMaintainedPackage is useful, if sparse. Encouraging new packages with no upstream targeted for Ubuntu to use this will create non-native packages, which will later be easier for Debian to adopt, if appropriate at that time. It also clearly separates packaging from development, which allows different specialisations if it becomes popular and attracts a community.

  • ApplicationIdeas needs a home, and probably a pointer to some process by which useful things could be accomplished, rather than the preparation of a list.

  • CategoryScience would really benefit from the attention of the Science team.

  • RealTime would benefit from some attention, perhaps especially from audio and telephony groups.

Tools

  • PbuilderHowto could use a refresh (or rewrite to use terms like "current development release", "current stable release", "current LTS release", etc.). Also, aren't there some scripts that do most of this now?

  • MultiDistroTools could use a refresh, an upstream, and maybe even a distributed package

  • MOTU/Packages/REVU/REVU-Tools should be stuck in the archives and referenced in the Reviewing guide

  • Strace is much harder to find than it should be

Specs

  • Spec/CodeReviewSLA should probably be reconcilied with REVU2 towards developing a workflow that is easy for everyone - we should base tools on workflow, not workflow on tools (especially when the tools don't yet exist)

  • DeveloperDocumentation should make the status as a Spec clearer.

  • ExistingDocumentation is unfinished, out of date, and the scope is undefined

  • AutomakeTransition should be more clearly highlighted. There's no reason this couldn't be advanced as part of merging (especially if patches flow back to the Debian BTS).

  • MotuProcessesSpec is a good spec, but these processes should be more clearly documented outside the spec to allow for changes over time.

  • EfficientCodingStrategySpec doesn't seem very lively, but information produced as a result would do well to be documented in the Development tree, so that people look for that when making adjustments.

  • ClosingBugsFromChangelog is done, and the results should be integrated everywhere else

  • APTPackageDeltas seems a useless discussion page, but is confusingly named given the terminology of Ubuntu package deltas for that distributed from http://patches.ubuntu.com/

  • Xdelta is confusingly named (it matches a universe package) If this isn't going anywhere, it should move into something else.

  • APTIndexDeltas seems to be another random branch in this forest

  • PackageNamingStandards doesn't seem to have gotten anywhere, and certainly doesn't provide any useful guidance

  • Spec/EasierMotuing still isn't. Ongoing work is great, but the recruiting, "career path", and guidelines for progression aren't clear yet.

  • PackageVersionConflicts is unfinished, hopeless out of date, and covers a namespace that would be better for helping with library transitions, or Debian/Ubuntu changes (especially build-dep, etc.).

  • SharingInformations is unfinished, out of date, and annoyingly named.

  • UseTheSpoon is unfinished and out of date

  • E17PackaagingPolicy is poorly named and unstarted. This should be generated or removed.

  • DCT/SpecDatabase seems extra somehow - shouldn't most DCT activities be integrated in Ubuntu development practices?

  • UbuntuPackagingGuide was a great spec, and did great things, but it should be moved into a clear Spec/ namespace, as the name can lead to confusion. There is a /Comments page that should stay with it.

  • TrackingUpstreamAndDebianVersions is nearly empty and frustratingly named for those searching for merge stuff.

  • UTFEightByDefault seems to predate specs. Is this done? If not, it needs a spec to be finished - enough is now UTF8 that the remainder may be considered broken.

  • DCT/SpecGeneratePackageLists would really benefit from flushing. Most of universe is fairly close to Debian, and the more MOTU supports DCT, the more we can focus on better integration between Universe and Main.

Teams

  • MOTU/Teams/Audio seems to have moved into Ubuntu Studio. or more generally into the Audio team (depending on which portion is considered)

  • MOTU needs signfiicant overhaul as part of the cleanup

  • UbuntuDevelopers is a good structure, but doesn't appear in line with current MOTU thinking. Also, as a team page, it should be more ... something.

  • UbuntuDevelopmentTeam seems a lost orphan - the content belongs somewhere else, or significantly more content belongs here.

  • MOTU/Teams/Ideas UDU was a long time ago, and not much here either 1) makes sense now, or 2) is of historical interest.

  • MOTU/Council/Charter seems a little out of date, and not really a Charter, or at least not formalised in such a way as to provide a good guide as to what properly belongs to MOTU Council, and what properly doesn't (I realise that this is yet to be strongly defined).

  • MOTU/Council Seems a much better treatment, and would do well to have a TOC and include the charter.

  • MOTU/Teams/IM is a nice page, but needs contact info, a link to an LP team, etc.

  • MOTU/Teams/Java is very out of date - this should be updated

  • MOTU/Teams/Games is not active, but has massive historical content. This should be cleaned up, relevant data moved to the Debian games team, etc.

  • MOTU/Teams/Python is a nice page, but needs contact info, a link to an LP team, etc.

Redirects

Odd External Result Pages

Miscellaneous Pages that are confusedly named

  • MorBuntu - also not very informative and out of date

  • UbuntuOnTheClamshell probably belongs as part of HW support (if something more detailed is not already there)

  • Messen/GeneralDocs appears to be part of a translation effort, but doesn't really contain General Docs (Und wenn man nicht Deutsches verstehen kann, alle ist nicht so klar).

  • HelpMiscellaneous has interesting content, but it should probably be elsewhere.

  • UbuntuGuide is outdated, and contains no useful information.

  • HelpOnPageCreation/PostInstallOperations is useful Wiki help, but might confuse those performing a title search on "Install"

MOTU/WikiCleanUp/SomeReviewNotes (last edited 2009-04-23 21:22:00 by pool-71-114-243-118)