Our docs are teh suck. Fix them up.
Our docs are teh suck. Fix them up.
My view is simple. I agree with comment 0. I disagree with closing this bug
until it is solved. Ultimately, it's going to be an ongoing thing, but having
the bug open, at the top of the list, alerts newcomers to the situation and
might encourage them to help us out.
Does that mean that you think this bug should never be closed, i.e. MW will
always have new or changed features, so the docs are never up to date?
Or, if not, what would it take to close it - are we just talking about end-user
documentation here? Would it be enough to fill in the holes at
[[mw:Help:Contents]]? Or do we need to get to the stage where there is a simple
mechanism for importing this documentation into a new wiki? Or that it is
included in a default MW install? Or have it in X (all?) languages?
Also, does this bug include technical docs as well as end-user docs?
I think Mark Clements is right, as MediaWiki changes, docs will need updating with new and existing feature modifications. There is no need to keep a bug open purely for prospect.
The bug is not meant to be closed. The goal is unattainable, which is why, by simple logical progression, it must stay open. Like the Christian concept of freedom from sin, we can only strive to fix bug 1, we can never actually fix it.
(In reply to comment #33)
Really, this should be a tracking bug. Can someone change the summary to
"Tracking bug for documentation issues", please?
It is a tracking bug, it doens't need to the word "tracking" to make it so.
Changed importance to "normal" level. Documentation never should be placed at a low priority unless the developing team or guy wants to be pocked every day with questions "how to do it", "how I can change it" etc.
Changing status to NEW, since the documentation issue will be a new one issue on every possible commit =)
A one-time comment to this tracking report: we are looking for documentation tasks that we could offer to Google Code-in participants.
Having spoken with the coordinators of the program and participant organizations it is clear that this program is good to complete dozens of little tasks that otherwise are sitting in backlogs forever. Many times bigger goals can be sliced in smaller tasks.
Your help selecting tasks is welcome. See https://www.mediawiki.org/wiki/Google_Code-In#Documentation.2FTraining
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)
@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.
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."