https://bugzilla.wikimedia.org/show_bug.cgi?id=46526
--- Comment #3 from Antoine "hashar" Musso <[email protected]> --- 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 :( -- You are receiving this mail because: You are the assignee for the bug. You are watching all bug changes. _______________________________________________ Wikibugs-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikibugs-l
