Last modified: 2014-11-20 09:10:12 UTC
Our docs are teh suck. Fix them up.
Need to adjust docs in the distribution tarball, and also the web site docs.
add dependency
I see that meta's Help:Contents has an effort to templateise (?) the help system, and make it exportable. Is there a plain text wikimarkup renderer? so we can just export a few wiki pages into plain text and have it automatically be included in the next tarball?
Source code comments got moved to phpdocumentor format by myself. The result can be seen at: http://wikipedia.sourceforge.net/mwdoc/ It currently just provide a skeleton, we have to comment source code now !
Created attachment 56 [details] A patch for version.php relating to documentation (see comment #6)
The patch I uploaded should take care of the 4 files remaining in the default module. (/maintenance/convertUtf8.php, /includes/SpecialData.php, /Version.php, and /includes/ZhConversion.php)
Created attachment 57 [details] Patch for \maintenance\convertUtf8.php relating to documentation (see comment #6)
Created attachment 58 [details] Patch for /includes/SpecialData.php
Created attachment 59 [details] Patch for /includes/ZhConversion.php
Created attachment 106 [details] diff to docs/skin.doc to describe how to start creating or modifying a skin I considered adding this type of information to http://meta.wikimedia.org/wiki/Skins but that doesn't really look related. Where should documentation about creating and modifying skins go?
Comment on attachment 56 [details] A patch for version.php relating to documentation (see comment #6) Version.php does no longer exist, marked as obsolete
Comment on attachment 57 [details] Patch for \maintenance\convertUtf8.php relating to documentation (see comment #6) Comment is already in the file
Comment on attachment 58 [details] Patch for /includes/SpecialData.php SpecialData does no longer exist
Comment on attachment 59 [details] Patch for /includes/ZhConversion.php ZhConversion.php has been documented already.
I added an url to the automatically generated todo list at http://wikipedia.sourceforge.net/doc/todolist.html which mostly contains documentation todos, let's get to it!
Lowering priority
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 - a new user appears, sees a hole and does a major bunch of useful updates and fades into the background - months pass with users making few tweaks here, a few additional items there but nothing substansive - repeat with another user 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".
It is an ongoing project as you said....no need to leave it open. Let us just fix it.
OK - fixed, verified and reopened in under 3 minutes. Does anyone want to comment? Rob - what's your view?
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?
*** Bug 3189 has been marked as a duplicate of this bug. ***
Comment on attachment 106 [details] diff to docs/skin.doc to describe how to start creating or modifying a skin Patch is obsolete, there is no includes/SkinPHPTal.php.
Neet
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.
http://en.wikipedia.org/wiki/Zeno%27s_paradoxes#Achilles_and_the_tortoise (bumping this bug to test bugmail configuration)
*** Bug 20000 has been marked as a duplicate of this bug. ***
oh noes
annoying bug to be CC'd on
Really, this should be a tracking bug. Can someone change the summary to "Tracking bug for documentation issues", please?
(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.
bug 22710, bug 19719, bug 2114, bug 14720, bug 12788, ... (161 results found)
> It is a tracking bug, it doens't need to the word "tracking" to make it > so. Correct, though it is a rather helpful convention.
*Bulk BZ Change: +Patch to open bugs with patches attached that are missing the keyword*
*** Bug 7947 has been marked as a duplicate of this bug. ***
Because of votes rasing importance/priority according to following scheme: 15+ votes - highest 5-15 votes - high Community must have a voice within development. Regards, Kozuch http://en.wikipedia.org/wiki/User:Kozuch
Tracking bugs usually are blockers for bug 2007.
It already implicitly blocks bug 2007 by blocking bug 700, so no need to block it directly as well.
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
