Documentation is out of date, incomplete (tracking)
Open, NormalPublic


Our docs are teh suck. Fix them up.

This tracking bug has been superseded by the Documentation project tag.
Please use the Documentation tag on tasks instead of making tasks block T2001.

(Previous discussion: T85485)

Version: unspecified
Severity: normal


T135107: Update wiki documentation for AuthManager
T110628: Improve AuthManager documentation
T126500: Organize a MediaWiki Documentation Day (similar to the Gerrit Cleanup Day)
T125275: Improve developer documentation for deferred updates
T122865: Create a wiki documentation page for each tool
T82096: update the multicast purging documentation
T98653: Improve deprecated JavaScript console warning messages to include links or copy-pasteable code
T85211: Content Translation FAQ page to be updated
T100527: Document/fix scripts for echo x1 DB requirements
T97946: Update VisualEditor's docs on errors/troubleshooting
T95060: Documentation for OOjs UI widgets needs to list what methods are available for each widget
T92585: MediaWiki logging/debugging documentation is out of date
T78512: Document BetaFeature's initialization requirement parameters
T67952: Update manual for Huggle to contain stuff for HG 3
T1355: Document installation steps for PSR-3 logging
T75603: [Story] update documentation of high-level data model
T71975: Document CI doc publishing process
T71499: Installation documentation should explain memcached
T71449: MediaWiki UI: VForm only partially documented
T73250: Documentation: JS Documentation out of date since OOJS move
T69938: Block::newFromTarget gets autoblocks when its documentation says it doesn't
T71372: Add README to skins folder
T71287: Document use of hiera settings to control expected hostnames
T74732: Quality Assurance/Browser testing/Setup instructions is out of date
T69490: style guide Typography page wrong and out-of-date
T64452: VisualEditor: Hide action=visualeditor from the api.php documentation output, given it's internal and not intended for third party use
T62793: Jenkins-mwext-sync needs documentation
T64446: Improve and better document process for uploading large files
T67794: Document/differentiate between use cases of formatTimePeriod() and formatDuration()
T64426: Undocumented inter-dependencies of default options (namely wgDefaultUserOptions['rcdays'] and wgRCMaxAge) with hard fail
T62719: On-request job queue handling needs RELEASE NOTES mention
T72633: Update documentation to incorporate mm-ch
T60922: Misleading documentation about markup examples for splitting long lists
T62587: State benefit(s) of chunked uploading in preference
T62567: Document $wgMFAnonymousEditing better
T62557: Update docs to deprecate $wgDefaultUserOptions['highlightbroken']
T70748: Upstream menu to OOjs UI and document so it appears in the styleguide
T70745: Implement (in core) and document MediaWiki UI tooltip library
T70741: Document reply fields
T64179: Echo API links to missing Echo API help page
T74275: no log in deployment-bastion:/data/project/logs from "503 server unavailable" on beta labs
T69183: Obsolete references to MessagesEn.php in several files under includes/*
T62464: $wgCacheDirectory dependency should be documented
T62462: $wgUpgradeKey is not commented out by default
T69167: Clear documentation should be provided about the *my* permissions
T60782: action=globalblock needs on-wiki documentation
T70632: Document how much memory Echo needs
T74163: Document new library requirements for logging interface, cdb, xhprof etc.
T65674: Document which modules do not need to be added to the dependencies of other modules
T68934: Help documentation should mention the cache time
T63886: Document in style guide how to use mw-ui-button on wiki using mw-ui-button span inside an anchor
T62195: Warning message is unclear when using a callback parameter while trying to get a token
T62192: Documentation and API are inconsistent (action=parse, contentmodel)
T60498: API action=review: wrong example on most wikis because it uses not existing parameter flag_accuracy
T58980: update browser test docs on mw.o
T63837: "Search and replace" dialog needs a help link for the "regular expression" handling
T72162: ZeroBanner doc still reference X-CS header when it is now X-CS2
T58864: FlaggedRevs: {{PENDINGCHANGELEVEL}} magic word is undocumented
T58860: Improve documentation of API's "dir" parameter
T60361: Flow: API needs documentation
T73892: Make commands in MobileFrontend need documentation
T65392: Add documentation of badgeItems setting
T73856: Update usage instructions for mw-ui-destructive
T61956: Document which designers are interested in a particular part of the user interface
T67035: action=mobileview live & doc mismatch
T65351: Document "Typography refresh/update" CSS changes for Vector
T66996: [Story] Automatically create Doxygen documentation of Wikibase PHP code
T68603: Update extension documentation with info about schema changes
T58621: Properly document the web API interface
T53503: ResoureLoader: Add self-explanatory comment to load.php about ResourceLoader
T63500: VisualEditor: Document what is needed in terms of support for custom MediaWiki skins
T61713: Document PPFrame constants
T63412: Misleading starttimestamp documentation in Edit API
T66813: Legend/help for colors needs to be added to user contribution page
T56890: Document 'update-guest-additions' and the issues it can often resolve
T68406: Documentation of API rollback action mentions delete instead of rollback
T63322: Enhance tutorial to trigger a job manually
T65033: Clarify how 'default' option should be used for preferences
T58368: Provide documentation for the user in the UI about the date formats accepted on date fields of AbuseFilter special pages
T59841: Update QA/testing documentation
T64946: Boolean preferences with default value of true cannot be changed if they do not have a key in $wgDefaultUserOptions
T59801: [EPIC] Improving the skinning experience for developers (improve documentation etc.)
T56701: add basic expectations management to docs
T56702: add Central Logging Service documentation
T58204: action=tokens API is basically not documented anywhere
T58192: Document how the entire browser test tool chain is set up
T58186: Document design and implementation of GWToolset
T56601: update "How to run browser tests" wiki page
T64810: Create TODO list for best MediaWiki API client library in Ruby
T64808: Create TODO list for best MediaWiki API client library in Perl
T64807: Create TODO list for best MediaWiki API client library in JavaScript
T64809: Create TODO list for best MediaWiki API client library in Python
T64806: Create TODO list for best MediaWiki API client library in Java
T52917: WikiEditor documentation is inadequate for user development
T57997: Need documentation for ip_in_range()
T52858: Document mw.uls.init
T54637: Update wikitech page on how to create a wiki
T57956: MobileFrontend geodata features (like Special:Nearby) have no documentation
T57946: Wikimedia Labs system admin (sysadmin) documentation sucks
T56364: Write proper documentation and tests for bug 50836
T57928: CORS docs for MediaWiki Web API?
T47965: list=tags output can depending on language
T57862: Flow: API missing examples and help URLs
T60994: Documentation of JobQueue::deduplicateRootJob is out of date
T46212: Suggest to users to install from git
T46211: Y U NO USE APC?
T47910: JJB: document "current build parameters" to trigger-build builder
T52674: Create an example JSON structure to be used in the navigation bar
T59317: Update MediaWiki's Bug life cycle diagram
T49541: Update the description of Extension:Score to include ABC notation.
T46127: Document JavaScript code in javascripts/common
T49486: memcached.txt needs updating
T54401: Message documentation missing for multiple strings
T57744: prop=videoinfo API viprop=derivatives parameter not documented in help
T57723: code documentation around wgUseFileCache
T44293: document Jenkins Job Builder
T57692: Document options for ext.translate.editor
T52552: README is unfocused & unwelcoming
T47745: MWScript usage documentation weird
T52514: Complete and document VisualEditor's integration and plugin system
T47601: [TUX] Update Translate extension documentation (regarding Proofread)
T45905: Document ResourceLoaderModule 'loaderScripts' property
T54150: Document
T44001: WikimediaMaintenance doesn't seem to have an extension page in
T45804: Docs about files needed by generateCollationData.php should be updated
T52319: Document how to add fonts
T50724: Improve API documentation for Wikibase
T49113: Use JSDuck syntax for inline examples in code documentation
T43956: Document how to implement tokens in (extension) api modules
T54068: Document grrrit-wm
T54026: Document PHP fatal and exception logging on the cluster (Ganglia graph, fatalmonitor script?)
T54006: Comment for $wgTranscludeCacheExpiry in DefaultSettings.php refers to other non-existing option
T55765: Syntaxhighlight: svn download of Geshi fails
T55716: document CI workflow using sequence diagram
T45591: Link translatable help pages on from the relevant special pages, actions etc.
T52107: Variable added_lines is now an array instead of a string
T40662: Document how fallback language and message loading order in general works
T48878: Clarify API class hierarchy
T50492: Clean up intro to InitialiseSettings.php
T50452: MediaWiki Language Extension Bundle needs better documentation (README containing links to help pages?)
T51989: Write documentation for UploadWizard in JSDuck format
T41979: Documentation is awful
T50337: Allow extensions to automatically generate jsduck documentation on
T50244: Upload GuidedTour jsduck documentation to Labs
T51843: Update securepoll documentation on wikitech
T53651: Auto-generated gadget documentation with JsDuck
T50216: Document how to debug Selenium tests
T50192: right-zero-edit should be defined
T53629: Document the stashed upload system better
T46913: Document deployment step by step on
T46904: update Gerrit/Git-related documentation after 2.6 upgrade
T48563: Standardise documentation for ResourceLoader modules inside module classes
T43378: Missing extension page
T48526: System documentation integrated in source code
T38757: Minimum version of MySQL
T36965: Clean up grammar in API autodocs
T36962: Some parameters' descriptions are unclear (titles, pageids, revids)
T46719: migrateCurStubs.php is mentioned in DefaultSettings but doesn't exist
T38609: Undocumented messages and parameters make translating harder
T34970: MW 1.18; How to determine the search profile / setting of a default search profile
T34919: Deployment documentation is out of date, incomplete
T39977: Need better documentation for how to checkout all extensions (for developers)
T34892: Special:Version should include version numbers of JS resources like jQuery
T39943: document deployment on beta
T46584: API data push/pull guidelines
T38437: A strict and correct Git workflow document is needed
T44892: Create "how to add plural support" tutorial/manual
T44893: Create "how to rewrite a log to use the new system" tutorial/manual
T39896: Message documentation needs updating
T44862: Create complete and up to date documentation on how to use job queue
T41349: Complete uploadcampaign api documentation
T39805: Create example extension for ResourceLoader
T39803: Write a step-by-step tutorial on how to use ResourceLoader in a (new) extension
T42937: Make sure all possible errors of action=upload are logged in getPossibleErrors
T44723: Update HISTORY with point release changes
T44687: action=options needs documentation
T33005: Functions / Properties should go into our doxygen docs + undoc'ed added
T46374: RL debug mode CSS docs incorrect
T41125: Document the Scribunto debug console messages
T42762: docs/hooks.txt is out of date
T31265: Mediawiki API documentation incomplete
T44518: Describe integration/* git repositories
T31143: Alias files seem undocumented
T40874: Minor bot edits don't trigger email notifications even with "E-mail me also for minor edits of pages" selected, and prevent subsequent notifications from any edit
T29306: Need a dedicated storage interface for extensions
T29215: Documentation not clear about the alias mw
T39151: Update extensions/README
T35827: the developer webpage URL is not very useful
T30660: SpecialSearchProfiles hooks is not documented well enough
T27408: Write style guide for function inline commenting
T30584: [EmailCapture] On-wiki documentation missing
T30542: Add @since information to more functions
T37467: Write docu/how-to for Windows with a GUI client
T32183: Document proper RTL support best practices on
T28905: OpenStackManager extension needs code documentation
T35637: Update on-wiki documentation of database layout for 1.19
T37403: Documentation for Gerrit on labs is almost as ugly as Gerrit itself
T33750: No info about a self-redirected page is shown when it's queried with &redirects
T28746: Document all caches and how to clear them
T35524: Jenkins: Publish error output of Doxyxgen
T23511: Document all parameters that can be used in LocalSettings.php
T28674: Document LQT code
T37234: Auto-generated API documentation should mention equivalent UI page
T31936: Api documentation on is out of date, incomplete
T35346: Update ResourceLoader documentation for Flipping functionality and 1.18's new position properties
T31768: Manual:Hooks/LoadExtensionSchemaUpdates is out of date
T23208: Upload API documentation
T33346: Help for Narayam
T28206: Add Documentation Page: Why isn't rXXXXX live on Wikipedia after it has been commited to SVN?
T19961: add comment to generateSitemap.php saying what is encoded
T27998: Write guidelines for extension organisation
T29650: Update Install/Upgrade documents on Manual:Upgrading and Manual:Installing_MediaWiki
T21175: Confusion around deleted messages in MediaWiki namespace
T21044: Document LanguageConverter
T14410: Documentation about character coding and conversion in MediaWiki
T10813: Documentation of $wgGroupPermissions is poor
T10629: $wgFilterCallback virtually totally undocumented
T17475: The Database module needs documentation updates
T5306: Add a description of "$wgLocalTZoffset = ..." to DefaultSettings.php
T5175: documentation files refers to .doc instead of .txt files
T8353: Full extension info (esp. URL) in all extensions
T4377: README, INSTALL, RELEASE-NOTES : AMP prerequisite information is inconsistent
T2373: PhpTal use of other skin stylesheet
T13102: Update Documentation in hooks.txt
T2007: Explain the wiki syntax in detailed EBNF
There are a very large number of changes, so older changes are hidden. Show Older Changes
Aklapper edited the task description. (Show Details)Jan 7 2015, 3:55 PM
Aklapper closed this task as "Declined".
yuvipanda reopened this task as "Open".Feb 14 2015, 4:31 AM
yuvipanda added a subscriber: yuvipanda.

Probably should be kept open until our documentation is perfect, up to date and complete. In a few hundred languages.

(I like having this bug be open, as a cultural admission of our documentation sucking)

Aklapper closed this task as "Declined".Feb 14 2015, 2:03 PM
Aklapper claimed this task.
Aklapper added a subscriber: Aklapper.

@yuvipanda: Did you also volunteer to keep the two places which track the very same thing (both the 'documentation' tag and this tracking task) in sync? If not, who will spend the time to do that?
I don't think "I like to keep this open due to cultural reasons" is a convincing reason for intentional untidyness in an issue tracker. If you like to be reminded that our documentation is bad, feel free to save this search query for open documentation tickets and put it in your list queries.

yuvipanda reopened this task as "Open".Feb 14 2015, 2:45 PM

Sure, I can write a bot that can keep them in sync.

Qgil removed Aklapper as the assignee of this task.Feb 14 2015, 3:01 PM
Qgil added a subscriber: Qgil.
Quiddity added a subscriber: Quiddity.EditedFeb 14 2015, 7:08 PM

I agree with yuvipanda. I think it is good to leave it 'open' as a symbol or meme or monument. People link to it more for the title ("Documentation is out of date, incomplete") than anything else. It's an iconic reminder. It's a forever unreachable goal, like the WMF Vision statement, that we are nevertheless always working towards.

It's a moment of levity, in an otherwise Serious Business world. It's a friendly/informal way of reminding each other, "dude, your documentation sucks" - instead we can say "oh, you might want to work on bug#(200)1 a little bit :) ". It's the best kind of 'inside joke', because newcomers can quickly figure out what is meant.

Practically/pragmatically speaking, I think it should be retired as an active *tracker* of any kind (to avoid confusion, and to avoid yuvi spending time writing a bot). [edit to highlight] But it's the one task that was never intended to be 'closed'.

to misquote: "there are three hard things in computer science: cache invalidation, naming things, up-to-date documentation, and off-by-one errors."

Legoktm edited the task description. (Show Details)Feb 14 2015, 7:12 PM
Dzahn added a subscriber: Dzahn.Mar 20 2015, 10:04 PM

there used to be the string "Reference to bz1" in this page until last week. i know because our watchmouse monitoring checks for that and is now not working anymore (T93443).

Dzahn removed a subscriber: Dzahn.May 29 2015, 1:29 AM
Qgil removed a subscriber: Qgil.Oct 11 2015, 8:29 PM
HappyDog removed a subscriber: HappyDog.Oct 12 2015, 8:56 PM
555 removed a subscriber: 555.Jan 30 2016, 2:58 AM
Meno25 removed a subscriber: Meno25.Feb 22 2016, 5:50 PM
Danny_B moved this task from Tag to Transition in progress on the Tracking board.Jul 10 2016, 10:39 PM

Add Comment