Our docs are teh suck. Fix them up.
Our docs are teh suck. Fix them up.
At www.mediawiki.org we are in the process of creating a comprehensive set of
docs for MediaWiki. This includes a set of public-domain help files, ultimately
for automatic inclusion in the Help: namespace of new wikis, and a detailed set
of technical documentation released under GFDL.
We would appreciate any help that people can offer, particularly from people who
know the codebase.
(re Assignment to Brion)
Is our lead developer now charged with the task of writing documentation AS WELL
as keeping the servers alive, keeping his technical staff in check, keeping his
volunteers from fucking up the codebase and more? That just doesn't seem fair...
The problem of documentation can be split into two; the code documentation
(which isn't too poor, considering) and the public-facing documentation (which
sucks like there's no tomorrow). Code documentation can be handled on an ongoing
basis by the development team. The public-facing documentation would be best off
taken up by a group, such as the one now operating on MediaWiki.org.
The public-facing documentation is slowly improving at MW.org, as is our more
detailed technical info (e.g. configuration settings, hooks, etc.)
There aren't many active contributors at the moment - the current pattern, in my
experience, seems to be
fades into the background
but nothing substansive
Eventually we will get a decent set of docs this way, but it will take years...
:( There are not many contributors who stay and continue to contribute with
regularity. I am one of the ones who have stayed and even I contribute much
less than would be ideal, and a fair amount of that is vandalism patrol (and
most of the rest is technical documentation or site structuring). Perhaps this
will change when we start moving content over from meta and there are more
people visiting the site as their first port-of-call. Or perhaps a more
concerted effort will be required.
That said, I am optimistic - the site is expanding and improving and becoming
more structured and the user base is definitely growing.
On another note, I am not at all clear what it would take for this bug to be
marked 'FIXED'. Really, it's an on-going project and there will always be work
to be done, as new versions are released and new features implemented.
I would suggest placing some concrete goals or closing the bug. Perhaps a good
target would be to make [[mw:Help:Contents]] into a complete list of areas we
want covered, and state that "this bug will be fixed when all direct links from
that page contain a minimum of 3 paragraphs".
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."