Re: [Wikitech-l] URLs for autogenerated documentation
On 02/08/2013 10:18 AM, Antoine Musso wrote: We would like to move the documentation to another host and I think it is a good time to change the URL as well to something a bit more meaningful than svn.mediawiki.org :-] I just wanted to say: YES, I agree, it is a good idea to move away from using svn in any URL having to do with our autogenerated documentation -- it's a misleading term now. :-) -- Sumana Harihareswara Engineering Community Manager Wikimedia Foundation ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
[Wikitech-l] URLs for autogenerated documentation
Hello, We have historically generated MediaWiki documentation on the Subversion server known as formey: https://svn.wikimedia.org/doc/ That the result of running doxygen once per day against the master branch of mediawiki/core.git. We would like to move the documentation to another host and I think it is a good time to change the URL as well to something a bit more meaningful than svn.mediawiki.org :-] We also have auto generated documentation for our puppet manifest at: http://doc.wikimedia.org/puppet/ Timo and I kind of disagree on the URL scheme to use to publish the documentation, so instead of starting a revert war in Gerrit, I thought it would be a good idea to ask some more people to participate in. For the context: We would like to have documentation generated for: - puppet - mediawiki branches and tags (PHP + JS + CSS) - mediawiki extensions (PHP + JS + CSS) The hosts doc.wikimedia.org and doc.mediawiki.org points to the same machine. I guess puppet could land at doc.wikimedia.org/puppet For MediaWiki we need the following parameters: - project (core / extension name) - version (tag / release branch / master) - type of documented source (php / js / css) What kind of magic ordering can we agree on? A) http://doc.wikimedia.org/mediawiki-core/branch|tag/php Would bring: doc.wikimedia.org/mediawiki-core/master/php doc.wikimedia.org/mediawiki-core/master/js doc.wikimedia.org/mediawiki-core/1.20.2/php doc.wikimedia.org/mediawiki-core/REL1_20/js doc.wikimedia.org/mediawiki-AbuseFilter/1.20.2/php B) doc.mediawiki.org/project/type/version/ Would bring: doc.mediawiki.org/core/php/master doc.mediawiki.org/core/js/master doc.mediawiki.org/core/php/1.20.2 doc.mediawiki.org/core/js/REL1_20 doc.mediawiki.org/AbuseFilter/php/REL1_20 Other thoughts? I would prefer having the MediaWiki doc hosted on the mediawiki.org domain. As for the ordering I guess we can bikeshed for a long time but most probably some ordering will seem natural for most people there :-] Thanks! -- Antoine hashar Musso ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] URLs for autogenerated documentation
Whichever way we chose, could we have http redirects from the old svn.wikimedia.org? There's a lot of urls that link there. I prefer doc.mediawiki.org/project/version/master (aka doc.mediawiki.org/core/master/php ) as in my mind, the hierarchy makes more sense like that, as the type of code is something more fine-grained than what version, and also something that belongs to the version number in a sense. I also like keeping the names MediaWiki and Wikimedia separate. At the end of the day it doesn't really matter which way though. It would also be cool if puppet docs were on doc.wikimedia.org, but if you had doc.mediawiki.org in the url, things auto redirected (and vice veras: if you went to doc.wikimedia.org/core/master/php things redirected to doc.mediawiki.org/core/master/php ) Cheers, Bawolff On Fri, Feb 8, 2013 at 11:18 AM, Antoine Musso hashar+...@free.fr wrote: Hello, We have historically generated MediaWiki documentation on the Subversion server known as formey: https://svn.wikimedia.org/doc/ That the result of running doxygen once per day against the master branch of mediawiki/core.git. We would like to move the documentation to another host and I think it is a good time to change the URL as well to something a bit more meaningful than svn.mediawiki.org :-] We also have auto generated documentation for our puppet manifest at: http://doc.wikimedia.org/puppet/ Timo and I kind of disagree on the URL scheme to use to publish the documentation, so instead of starting a revert war in Gerrit, I thought it would be a good idea to ask some more people to participate in. For the context: We would like to have documentation generated for: - puppet - mediawiki branches and tags (PHP + JS + CSS) - mediawiki extensions (PHP + JS + CSS) The hosts doc.wikimedia.org and doc.mediawiki.org points to the same machine. I guess puppet could land at doc.wikimedia.org/puppet For MediaWiki we need the following parameters: - project (core / extension name) - version (tag / release branch / master) - type of documented source (php / js / css) What kind of magic ordering can we agree on? A) http://doc.wikimedia.org/mediawiki-core/branch|tag/php Would bring: doc.wikimedia.org/mediawiki-core/master/php doc.wikimedia.org/mediawiki-core/master/js doc.wikimedia.org/mediawiki-core/1.20.2/php doc.wikimedia.org/mediawiki-core/REL1_20/js doc.wikimedia.org/mediawiki-AbuseFilter/1.20.2/php B) doc.mediawiki.org/project/type/version/ Would bring: doc.mediawiki.org/core/php/master doc.mediawiki.org/core/js/master doc.mediawiki.org/core/php/1.20.2 doc.mediawiki.org/core/js/REL1_20 doc.mediawiki.org/AbuseFilter/php/REL1_20 Other thoughts? I would prefer having the MediaWiki doc hosted on the mediawiki.org domain. As for the ordering I guess we can bikeshed for a long time but most probably some ordering will seem natural for most people there :-] Thanks! -- Antoine hashar Musso ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] URLs for autogenerated documentation
On Feb 8, 2013, at 7:18 AM, Antoine Musso hashar+...@free.fr wrote: A) http://doc.wikimedia.org/mediawiki-core/branch|tag/php Would bring: doc.wikimedia.org/mediawiki-core/master/php doc.wikimedia.org/mediawiki-core/master/js doc.wikimedia.org/mediawiki-core/1.20.2/php doc.wikimedia.org/mediawiki-core/REL1_20/js doc.wikimedia.org/mediawiki-AbuseFilter/1.20.2/php B) doc.mediawiki.org/project/type/version/ Would bring: doc.mediawiki.org/core/php/master doc.mediawiki.org/core/js/master doc.mediawiki.org/core/php/1.20.2 doc.mediawiki.org/core/js/REL1_20 doc.mediawiki.org/AbuseFilter/php/REL1_20 I would prefer having the MediaWiki doc hosted on the mediawiki.org domain. As for the ordering I guess we can bikeshed for a long time but most probably some ordering will seem natural for most people there :-] Thanks! Presenting them as A and B seems flawed as they are separate things: Let's decouple them into a matrix of more tangible decisions: A) Do we want to maintain two domain names for our documentation? No, * We already have doc.wikimedia.org, doc.mediawiki.org would be a new one * If we maintain separate domain names, when is something mediawiki and when is it wikimedia? For example, documentation for jQuery plugins, VisualEditor etc are stand alone, most certainly not MediaWiki specific. There is no reason to force ourselves into this ambiguity. One domain is all we need. With some redirects perhaps. B) Hierarchy of directories project, branch and category of code (usually a programming language). 6 possible combinations of these 3. *The one I've proposed before and rationalised in the comment thread is project branch code-category. * This because not all projects have the same code categories. A tree is usually structured towards more specificity down the tree. * With the separator of time as high up as possible so that you don't duplicate versions in multiple locations. * Easier to maintain if we rename the code categories later on. * Easier to generate to have everything go in 1 target directory and not separate directories in different locations. I appreciate you putting thought into these minor details, but I think this discussion is pointless because you're not providing any rational input yourself (all I see it I prefer which is undeniably a useless argument to defend against). I can talk for hours, but it help get the documentation deployed if you don't communicate. The thread can become slightly more useful if you had actually provided some arguments of your own. I've explained the reasons for my version, then you reverted it with no explanation, linking[1] only to this post on wikitech-l, where you merely present A and B once again with no explanation as to why you disagree in the first place. I'd love to discuss the advantage of your version or disadvantage of mine, preferably as a simple response to my question in Gerrit, but here is fine too. Let's keep in mind the bigger picture and do what's best for the users. On Feb 8, 2013, at 7:41 AM, bawolff bawolff...@gmail.com wrote: Whichever way we chose, could we have http redirects from the old svn.wikimedia.org? There's a lot of urls that link there. Unrelated. Yes, of course. When we move it, the old location will become a redirect. I prefer doc.mediawiki.org/project/version/master (aka doc.mediawiki.org/core/master/php ) as in my mind, the hierarchy makes more sense like that, as the type of code is something more fine-grained than what version, and also something that belongs to the version number in a sense. I also like keeping the names MediaWiki and Wikimedia separate. At the end of the day it doesn't really matter which way though. I agree. It would also be cool if puppet docs were on doc.wikimedia.org, but if you had doc.mediawiki.org in the url, things auto redirected (and vice veras: if you went to doc.wikimedia.org/core/master/php things redirected to doc.mediawiki.org/core/master/php ) I'm not sure we should be maintaining two domains. We can have doc.mediawiki.org redirect to doc.wikimedia.org/mediawiki-core, but to maintain both would be confusing, decentralising and depending on the implementation, it would encourage using multiple urls for the same thing. Might as well stick with one canonical url. Best, -- Krinkle [1] https://gerrit.wikimedia.org/r/39212 ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] URLs for autogenerated documentation
Before we get too entrenched in the address layout, can we have a better url than doc, it doesn't really scream out what it does, Something along the lines documentation or development (probably not so much) suggest better about what the address will contain. On Sat, Feb 9, 2013 at 1:37 PM, Krinkle krinklem...@gmail.com wrote: On Feb 8, 2013, at 7:18 AM, Antoine Musso hashar+...@free.fr wrote: A) http://doc.wikimedia.org/mediawiki-core/branch|tag/php Would bring: doc.wikimedia.org/mediawiki-core/master/php doc.wikimedia.org/mediawiki-core/master/js doc.wikimedia.org/mediawiki-core/1.20.2/php doc.wikimedia.org/mediawiki-core/REL1_20/js doc.wikimedia.org/mediawiki-AbuseFilter/1.20.2/php B) doc.mediawiki.org/project/type/version/ Would bring: doc.mediawiki.org/core/php/master doc.mediawiki.org/core/js/master doc.mediawiki.org/core/php/1.20.2 doc.mediawiki.org/core/js/REL1_20 doc.mediawiki.org/AbuseFilter/php/REL1_20 I would prefer having the MediaWiki doc hosted on the mediawiki.org domain. As for the ordering I guess we can bikeshed for a long time but most probably some ordering will seem natural for most people there :-] Thanks! Presenting them as A and B seems flawed as they are separate things: Let's decouple them into a matrix of more tangible decisions: A) Do we want to maintain two domain names for our documentation? No, * We already have doc.wikimedia.org, doc.mediawiki.org would be a new one * If we maintain separate domain names, when is something mediawiki and when is it wikimedia? For example, documentation for jQuery plugins, VisualEditor etc are stand alone, most certainly not MediaWiki specific. There is no reason to force ourselves into this ambiguity. One domain is all we need. With some redirects perhaps. B) Hierarchy of directories project, branch and category of code (usually a programming language). 6 possible combinations of these 3. *The one I've proposed before and rationalised in the comment thread is project branch code-category. * This because not all projects have the same code categories. A tree is usually structured towards more specificity down the tree. * With the separator of time as high up as possible so that you don't duplicate versions in multiple locations. * Easier to maintain if we rename the code categories later on. * Easier to generate to have everything go in 1 target directory and not separate directories in different locations. I appreciate you putting thought into these minor details, but I think this discussion is pointless because you're not providing any rational input yourself (all I see it I prefer which is undeniably a useless argument to defend against). I can talk for hours, but it help get the documentation deployed if you don't communicate. The thread can become slightly more useful if you had actually provided some arguments of your own. I've explained the reasons for my version, then you reverted it with no explanation, linking[1] only to this post on wikitech-l, where you merely present A and B once again with no explanation as to why you disagree in the first place. I'd love to discuss the advantage of your version or disadvantage of mine, preferably as a simple response to my question in Gerrit, but here is fine too. Let's keep in mind the bigger picture and do what's best for the users. On Feb 8, 2013, at 7:41 AM, bawolff bawolff...@gmail.com wrote: Whichever way we chose, could we have http redirects from the old svn.wikimedia.org? There's a lot of urls that link there. Unrelated. Yes, of course. When we move it, the old location will become a redirect. I prefer doc.mediawiki.org/project/version/master (aka doc.mediawiki.org/core/master/php ) as in my mind, the hierarchy makes more sense like that, as the type of code is something more fine-grained than what version, and also something that belongs to the version number in a sense. I also like keeping the names MediaWiki and Wikimedia separate. At the end of the day it doesn't really matter which way though. I agree. It would also be cool if puppet docs were on doc.wikimedia.org, but if you had doc.mediawiki.org in the url, things auto redirected (and vice veras: if you went to doc.wikimedia.org/core/master/php things redirected to doc.mediawiki.org/core/master/php ) I'm not sure we should be maintaining two domains. We can have doc.mediawiki.org redirect to doc.wikimedia.org/mediawiki-core, but to maintain both would be confusing, decentralising and depending on the implementation, it would encourage using multiple urls for the same thing. Might as well stick with one canonical url. Best, -- Krinkle [1] https://gerrit.wikimedia.org/r/39212 ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
