Last modified: 2014-09-24 00:16:45 UTC
Proposed by Aaron Schulz and extracted from http://www.mediawiki.org/wiki/Mentorship_programs/Possible_projects#System_documentation_integrated_in_source_code "It would be really nice if inline comments, README files, and special documentation files could exist in the source code but be exported into a formatted, navigable system (maybe wiki pages or maybe something else). It could be something like doxygen, accept better and orientated to admins and not developers. Of course it should integrate with mediawiki.org and http://svn.wikimedia.org/doc. The idea would be that one could: * Keep documentation close to the code and thus far more up to date * Even enforce documentation updates to it with new commits sometimes * Reduce the tedium of making documentation by using minimal markup to specify tables, lists, hierarchy, and so on, and let a tool deal with generating the html (or wikitext). This could allow for a more consistent appearance to documentation. * When things are removed from the code (along with the docs in the repo), if mw.org pages are used, they can be tagged with warning box and be placed in maintenance category." Submitted here for feedback. If we can have a rough plan and at least one potential mentor perhaps we could push this project idea to https://www.mediawiki.org/wiki/Summer_of_Code_2013#Project_ideas
(In reply to comment #0) > http://svn.wikimedia.org/doc https://doc.wikimedia.org/ now. I hope it's clear for potential contributors that we're not after writing a new documentation (deployment) system from scratch, but first to come up with a rough plan with executable, handable subtasks that are (hopefully) based on existing tools and infrastructure (e.g. improving oxygen). :)
We need to make this proposal clear to ourselves before attempting to propose it to contributors. When I read the proposal I see an extension able to go through the source code of MediaWiki core and extension, capture the documentation and export it to structured MediaWiki pages e.g. under the "Docs:" namespace. Those pages wouldn't be editable, and whenever there is a change in the source code there the corresponding updates would be made in the wiki pages. I have no idea / no opinion about the implementation, other than yes, let's reuse as much as possible software available out there and maintained by others. ... but I'm not sure whether this is in line with what Aaron / others have in mind. CCing Chad and hashar for ideas & sanity check.
At first: This project should NOT be handled as a GSOC 2013 project. It is prone to failure. We have such a debt on this subject that there is no way a new comer will solve it or even come close to an idea of a solution in less than 8 weeks. GSOC should be for what it is: small projects for newbies :-] It is not going to help us nor the student. ------ My points regarding documentation is very simple: - we have almost no documentation (nor any tutorials) - I do not care about the documentation on mediawiki.org. It is almost never accurate. Most of the time I do not read our inline comments and documentation either. It is either very incomplete, sometime misleading and most of the time not present at all. Solutions: read the code, ask the original developer. To answer the proposal in comment #0 > Keep documentation close to the code and thus far more up to date > Even enforce documentation updates to it with new commits sometimes We need to first start writing documentation. Until we do, there is no point in setting up whatever crazy system. The root issue is we suck at writing doc. The documentation should be kept in sync with the code. The best way to handle that is to have the doc+code changes to be atomic, hence to land in the source tree as a single commit. Then we can use whatever tool to generate the documentation automatically (we use Doxygen for now). > Reduce the tedium of making documentation by using minimal markup to specify tables, lists, hierarchy, and so on, and let a tool deal with generating the html (or wikitext). This could allow for a more consistent appearance to documentation. Markup is totally irrelevant. Doxygen let you put HTML in it, it even sometime support something close to wikitext (like stars to build a list). All the nice markup is not going to be useful when there is no text to actually format (see point 1: we suck at writing doc). > When things are removed from the code (along with the docs in the repo), if mw.org pages are used, they can be tagged with warning box and be placed in maintenance category." Trivially solved by keeping the code and documentation at the same place and with review. If the proposal is to get some kind of robots that analyze the code to then update the wiki and wait for some random non-dev to edit the wiki: it is prone to failure. My recommendation would be to make the documentation a focus for next fiscal year. Start having old developers write tutorial and write documentation while they are mentoring new developers. But we all know we are too busy to handle that. So I guess it is going to be a dead horse. Sorry :(
A few questions come to mind reading this proposal: 1. Does anyone have ideas on how we can keep documentation translatable if it is somehow part of the code? MediaWiki.org currently has this possibility. 2. It is widely known and documented (pun intended), that developers are not great writers, nor ideal people to train wiki administrators and wiki operators. How will non-developers be able to contribute, especially as we move away for the wiki engine as a documentation mechanism? Comment 3 addresses some more issues that will not be resolved by throwing away our current documentation, however incomplete and sometimes out of date, and starting something new. And before we can start something new, we will probably have to bikeshed on it for a few years. This issue could be WONTFIXed, if you'd ask me. Take an example from Nike's slogan, and reserve time in your development cycles to actually allow others to learn what you already know, be it as a written tutorial, properly prepared web cast, documentation page, or whatever: Just do it!
Perhaps too hard to start with MediaWiki core, but would be nice to get that with extensions, so MediaWiki pages could almost be automatically generated, and a step towards bug 26992.
Ok, I have removed this proposal as a GSOC 2013 candidate. I still believe it is worth discussing the proposal, though. "Develop clear documentation and APIs to enable developers to create applications that work easily with MediaWiki" is a top WMF priority according to http://strategy.wikimedia.org/wiki/Wikimedia_Movement_Strategic_Plan_Summary/Stabilize_Infrastructure API documentation is usually written in the source code. "Keep documentation close to the code" is a general principle of good open source software development. This request is about "system documentation", tutorials et al are different beats, out of scope here. About L10n, I'm sure we are not the first project with this problem. It is a convention to document in source code in English. Localization of source code exists but afaik it focuses in UI strings, no docs (but I could be wrong). If the docs would be exported to MediaWiki pages, then you could have your translation point there, using the same workflow being used e.g. at mediawiki.org. The fact that the English / source page is updated manually or by a sync with source code shouldn't be relevant to translators. They would get the same notifications when new updates are available, and the UI of those wiki page would have the same language bar we have for manually updated pages. Of course a main point to argue is whether we can just keep using https://en.wikipedia.org/wiki/Doxygen and integrate https://doc.wikimedia.org/ better to mediawiki.org. And I agree with hashar that having good docs (in whatever form) is the first priority, otherwise the doc tools are just pointless. This is why I digged that URL reminding us what are our top priorities until 2015.
Has there been any progress on this proposal since March? (In reply to comment #3) > This project should NOT be handled as a GSOC 2013 project. It is prone to > failure. We have such a debt on this subject that there is no way a new comer > will solve it or even come close to an idea of a solution in less than 8 > weeks. Is there a portion of this task that could be proposed as a GSoC / OPW project?
(In reply to comment #7) > Is there a portion of this task that could be proposed as a GSoC / OPW > project? Not really. It would require a cultural change among developers, for example rejecting patches which do not come with inline documentation / examples. I can't see us enforcing writing documentation anytime soon since most of our code is undocumented anyway. And of course, we lack resource to document our existing code.
(In reply to comment #8) > (In reply to comment #7) > > Is there a portion of this task that could be proposed as a GSoC / OPW > > project? > > Not really. It would require a cultural change among developers, for example > rejecting patches which do not come with inline documentation / examples. I > can't see us enforcing writing documentation anytime soon since most of our > code is undocumented anyway. And of course, we lack resource to document our > existing code. Is this simply a WONTFIX, then?
Hi, this project is still listed at https://www.mediawiki.org/wiki/Mentorship_programs/Possible_projects#System_documentation_integrated_in_source_code Should this project be still listed in that page? If not, please remove it. If it still makes sense, then it could be moved to the "Featured projects" section if it has community support and mentors.
