Too many cooks spoil the broth---or: how about we clean up the wiki?
Hello everyone, <rant>Today I looked at our wiki to add roadmaps for some products and realized what a mess the wiki is. This wasn't obvious to me, because I stopped using the wiki long ago, well, because it was such a mess. But boy, it has become worse!</rant> I think the main problem is that there's no obvious structure in the wiki, so everyone just adds their stuff anywhere, maybe thinking that someone else will move it to the right place. The other problem is that there's no such person cleaning up. Here's my plan: I'd like to rename (possibly a lot of) wiki pages so that the naming scheme implies a kind of wiki structure. I'd also add a page saying where stuff should go, and we'll beat up everyone not adhering to the structure in a joint effort. By the way, what happens if we rename wiki pages? I guess Trac will update all internal links, but external links (e.g., from the website) will be broken? We could fix our own website, but other websites would still be broken. How bad would that be? Here's a suggested naming scheme. In this scheme, there are three top-level directories (or rather, page prefixes): - doc/ contains all documentation for Tor users, relay operators, and the community in general. This is the stuff that people would usually expect in a wiki. - org/ contains deliverables promised to our sponsors, meeting plans, product roadmaps, project progress, etc. This stuff is in the wiki to make Tor development as transparent as possible. In theory, non-developers wouldn't require write permissions to these pages. - trac/ contains Trac's own documentation that it generously dumped into our Tor wiki. In theory, nobody would require write permissions to these pages. I'll go through the existing wiki pages and say where they should go. The following pages would move to doc/ (e.g., "DNS Hijacking" would become "doc/DNS Hijacking"): DNS Hijacking HTTPSEverywhere/SSLObservatorySubmission ImportantGoogleChromeBugs OnionCat TorALaymansGuide TorFAQUnanswered TorInChroot TorToggle UsingTorWithVservers badRelays badRelays/trotskyIps talks talks/MoscowState2010 TheOnionRouter TheOnionRouter/AnonymousPublicSpeech TheOnionRouter/BIND TheOnionRouter/BandwidthLimitChangeController TheOnionRouter/BlockNonTorTrafficDebian TheOnionRouter/BlockingDiagnostics TheOnionRouter/BlockingIrc TheOnionRouter/CentralizedTorServer TheOnionRouter/ConnectOverSSH TheOnionRouter/ContestEntries TheOnionRouter/ContestEntries/DesignFeedback TheOnionRouter/CronBandwidthLimit TheOnionRouter/DebianLive TheOnionRouter/EmbeddedTips TheOnionRouter/ExitEnclave TheOnionRouter/FAQUnanswered TheOnionRouter/FireFoxTorPerf TheOnionRouter/FirefoxRemoteDNS TheOnionRouter/GoodBadISPs TheOnionRouter/Gsoc2009 TheOnionRouter/Gsoc2009/ThandyTorrents TheOnionRouter/HiddenServiceNames TheOnionRouter/HowTo_post_on_or-talk_mailinglist TheOnionRouter/LegalStuff TheOnionRouter/LiveCDBestPractices TheOnionRouter/MacOSXUpgradeToTrunk TheOnionRouter/OpenbsdChrootedTor TheOnionRouter/OpenbsdChrootedTorControlScript TheOnionRouter/OpenbsdChrootedTorScript TheOnionRouter/OperationalSecurity TheOnionRouter/Portable_Tor TheOnionRouter/PreventingDnsLeaksInTor TheOnionRouter/Preventing_Tor_DNS_Leaks TheOnionRouter/PrivoxyConfig TheOnionRouter/PrivoxyPatches TheOnionRouter/Publicfile TheOnionRouter/ReducedExitPolicy TheOnionRouter/RemailingAndTor TheOnionRouter/RunTwoPrivoxys TheOnionRouter/SshPortForwardedTor TheOnionRouter/SummerOfCode TheOnionRouter/SupportPrograms TheOnionRouter/SupportPrograms/Polipo TheOnionRouter/TSocksPatches TheOnionRouter/TermsObserved TheOnionRouter/TorAbuseTemplates TheOnionRouter/TorExitNodeHowto TheOnionRouter/TorGuideUniversities TheOnionRouter/TorInChroot TheOnionRouter/TorInChroot-new TheOnionRouter/TorInTheMedia TheOnionRouter/TorMirror TheOnionRouter/TorOnDebian/PackagesForArchitectures TheOnionRouter/TorShirt TheOnionRouter/TorWin32TorWS TheOnionRouter/TorALaymansGuide TheOnionRouter/TorDNSExitList TheOnionRouter/TorFAQ TheOnionRouter/TorIPCOP TheOnionRouter/TorifyHOWTO TheOnionRouter/TorifyHOWTO/EMail TheOnionRouter/TorifyHOWTO/FTP TheOnionRouter/TorifyHOWTO/InstantMessaging TheOnionRouter/TorifyHOWTO/IrcSilc TheOnionRouter/TorifyHOWTO/Misc TheOnionRouter/TorifyHOWTO/Misc/Putty TheOnionRouter/TorifyHOWTO/Putty TheOnionRouter/TorifyHOWTO/SystracePolicy TheOnionRouter/TorifyHOWTO/WebBrowsers TheOnionRouter/Torouter TheOnionRouter/Torouter_notes TheOnionRouter/Torwin32DNS TheOnionRouter/Transocks TheOnionRouter/TransocksifyingTor TheOnionRouter/TransparentProxy TheOnionRouter/VMWareThroughTor TheOnionRouter/VerifyingSignatures TheOnionRouter/WebProxyHowto TheOnionRouter/Wikipedia TheOnionRouter/WindowsBufferProblems CodingForTor CodingForTor/CodingInC CodingForTor/CodingInR CodingForTor/LoggingAndDocumentation CodingInC CoreTorTracUsers build build/AddingBuildSlaves build/BuildSignoff build/ListOfPackages dev/HowToReleaseTor dev/SupportPolicy dev/SupportPolicy_v2 The following pages would move to org/meetings/: 2010TorAnnualDevMeeting 2011MiniDevMeeting 2011MiniDevMeeting/notes 2011StockholmHackfest 2011TorAnnualDevMeeting The product roadmaps that are not there yet would go into org/roadmaps/. Everything related to project management would go into org/projects/: TorAgileProcess projects/HowWeDoProjectManagement projects/ProjMgt/SetUpProjectMgt Products projects/ProductsandAssignments projects projects/2009FinancialandComplianceAudit projects/BridgeDB projects/CalculateDirreqShares projects/EmailAutoResponder projects/ExperimentalBridgeBundles projects/Infrastructure projects/Metrics projects/Metrics/DesignAndDeployDescriptorDatabase projects/Metrics/ImproveMetricsPortal projects/Metrics/PublishMetricsDataAndTools projects/Metrics/SafelyCountClients projects/Thandy projects/Tor projects/TorBrowserBundle projects/TorBrowserBundle/Alpha projects/TorBrowserBundle/OSX projects/TorBrowserBundle/OSX/Security projects/TorBulkExitlist projects/TorButton projects/TorCheck projects/TorFlow projects/TorStatus projects/Tor/MultithreadedCrypto projects/Weather projects/arm projects/mirror projects/mirror/torrent projects/vidalia The deliverables promised to our sponsors would go into org/sponsors/: sponsors sponsors/SponsorA sponsors/SponsorB sponsors/SponsorD sponsors/SponsorD/December2010 sponsors/SponsorD/June2011 sponsors/SponsorD/March2011 sponsors/SponsorD/September2010 sponsors/SponsorE sponsors/SponsorE/PhaseOne sponsors/SponsorF sponsors/SponsorF/Year1 And finally, the following pages are about using Trac and would go into trac/ (it's possible that Trac wouldn't like us renaming some of its pages, but I guess we'll find out): InterTrac InterWiki RecentChanges TitleIndex TracAccessibility TracAdmin TracBackup TracBrowser TracCgi TracChangeset TracEnvironment TracFastCgi TracFineGrainedPermissions TracGuide TracImport TracIni TracInstall TracInterfaceCustomization TracLinks TracLogging TracModPython TracModWSGI TracNavigation TracNotification TracPermissions TracPlugins TracQuery TracReports TracRevisionLog TracRoadmap TracRss TracSearch TracStandalone TracSupport TracSyntaxColoring TracTickets TracTicketsCustomFields TracTimeline TracUnicode TracUpgrade TracWiki TracWorkflow WikiDeletePage WikiFormatting WikiHtml WikiMacros WikiNewPage WikiPageNames WikiProcessors WikiRestructuredText WikiRestructuredTextLinks WikiStart That's it. I realize there are lots of cooks on this list, so I expect there will be feedback. Thanks, Karsten
On 2011-Jun-10 12:08, Karsten Loesing wrote: [..]
Here's my plan: I'd like to rename (possibly a lot of) wiki pages so that the naming scheme implies a kind of wiki structure. I'd also add a page saying where stuff should go, and we'll beat up everyone not adhering to the structure in a joint effort.
Why not use Categories? That avoids changing any URLs and also puts them into a kind-of-structure. I agree though, that a structure in the URL is probably better from a visible point of view, but most folks don't look at URLs anymore anyway. Greets, Jeroen
On 6/10/11 1:30 PM, Jeroen Massar wrote:
On 2011-Jun-10 12:08, Karsten Loesing wrote: [..]
Here's my plan: I'd like to rename (possibly a lot of) wiki pages so that the naming scheme implies a kind of wiki structure. I'd also add a page saying where stuff should go, and we'll beat up everyone not adhering to the structure in a joint effort.
Why not use Categories? That avoids changing any URLs and also puts them into a kind-of-structure.
I agree though, that a structure in the URL is probably better from a visible point of view, but most folks don't look at URLs anymore anyway.
I guess Categories are a Trac plugin that's not installed by default, right? And of course I was unable to find it. Do you have a link? Thanks, Karsten
On Fri, Jun 10, 2011 at 12:08:46PM +0200, karsten.loesing@gmx.net wrote 7.5K bytes in 279 lines about: : I think the main problem is that there's no obvious structure in the : wiki, so everyone just adds their stuff anywhere, maybe thinking that : someone else will move it to the right place. The other problem is that : there's no such person cleaning up. You're looking at the structure as created and migrated over 8 years. Also see https://trac.torproject.org/projects/tor/ticket/1939 for another option. Our wiki is trying to be all things to all people, and is clearly failing, or at least confusing everywhere. Trac search isn't very good. Lots of people use https://trac.torproject.org/projects/tor/wiki/TitleIndex to find their way around the wiki. Most of this is going to be a "do-acracy", he/she who does the work, wins. The only part to be careful with is the actual faq pages. Those are heavily linked from around the world. I can pull up the view of our trac according to google's webmaster tools if you're interested. -- Andrew pgp key: 0x74ED336B
On 6/10/11 2:03 PM, andrew@torproject.org wrote:
On Fri, Jun 10, 2011 at 12:08:46PM +0200, karsten.loesing@gmx.net wrote 7.5K bytes in 279 lines about: : I think the main problem is that there's no obvious structure in the : wiki, so everyone just adds their stuff anywhere, maybe thinking that : someone else will move it to the right place. The other problem is that : there's no such person cleaning up.
You're looking at the structure as created and migrated over 8 years. Also see https://trac.torproject.org/projects/tor/ticket/1939 for another option. Our wiki is trying to be all things to all people, and is clearly failing, or at least confusing everywhere.
Interesting, I hadn't seen #1939 before. I think having a development status page would be great. I might even write one at some point. But I think having a clearer separation between the documentation part of the wiki and the development part would be even useful when we have such a development status page.
Trac search isn't very good. Lots of people use https://trac.torproject.org/projects/tor/wiki/TitleIndex to find their way around the wiki.
Yes, that's how I find stuff, too. Unfortunately, that approach depends very much on meaningful URLs/wiki page names.
Most of this is going to be a "do-acracy", he/she who does the work, wins. The only part to be careful with is the actual faq pages. Those are heavily linked from around the world.
Which pages are that? The ones starting with TheOnionRouter/ ? And should we put in redirects for those pages, at least for the next 6 or 12 months?
I can pull up the view of our trac according to google's webmaster tools if you're interested.
Yes, having the Google Webmaster Tools output might be useful. Can you make that available somewhere? Thanks, Karsten
On Fri, 10 Jun 2011 12:08:46 +0200 Karsten Loesing <karsten.loesing@gmx.net> wrote:
By the way, what happens if we rename wiki pages? I guess Trac will update all internal links, but external links (e.g., from the website) will be broken? We could fix our own website, but other websites would still be broken. How bad would that be?
Do you plan to fix links in the mailing list archives as well? How about links in our e-mail inboxes? Also, I would expect Trac to *not* update wiki-internal links -- it doesn't update ticket ‘components’ when a component is renamed or deleted.
And finally, the following pages are about using Trac and would go into trac/ (it's possible that Trac wouldn't like us renaming some of its pages, but I guess we'll find out):
Several parts of the Trac interface that you would be unable to modify link to these pages. (Most notably, there is a link to ‘WikiFormatting’ above the ‘Comment’ entry box on every ticket.) Robert Ransom
On 6/11/11 6:13 AM, Robert Ransom wrote:
On Fri, 10 Jun 2011 12:08:46 +0200 Karsten Loesing <karsten.loesing@gmx.net> wrote:
By the way, what happens if we rename wiki pages? I guess Trac will update all internal links, but external links (e.g., from the website) will be broken? We could fix our own website, but other websites would still be broken. How bad would that be?
Do you plan to fix links in the mailing list archives as well? How about links in our e-mail inboxes?
Nope. But we could add redirects for those pages linked from the mailing list archives and everyone's inbox. Similar to how we added redirects when moving from https://wiki.torproject.org/noreply/TheOnionRouter/ to the current location.
Also, I would expect Trac to *not* update wiki-internal links -- it doesn't update ticket ‘components’ when a component is renamed or deleted.
I just tried it and it looks good. So yes, Trac does update wiki-internal links.
And finally, the following pages are about using Trac and would go into trac/ (it's possible that Trac wouldn't like us renaming some of its pages, but I guess we'll find out):
Several parts of the Trac interface that you would be unable to modify link to these pages. (Most notably, there is a link to ‘WikiFormatting’ above the ‘Comment’ entry box on every ticket.)
Right, I had pages like WikiFormatting in mind when adding the comment that Trac might not like us renaming some of its pages. I guess we can find out if Trac is smart enough to update these links, too. Or we can try using redirects for these pages, too. If neither works, it's not the end of the world to leave these pages where they are. Best, Karsten
On Sat, Jun 11, 2011 at 08:17:35AM +0200, karsten.loesing@gmx.net wrote 2.5K bytes in 34 lines about: : > Do you plan to fix links in the mailing list archives as well? How : > about links in our e-mail inboxes? : : Nope. But we could add redirects for those pages linked from the : mailing list archives and everyone's inbox. Similar to how we added : redirects when moving from : https://wiki.torproject.org/noreply/TheOnionRouter/ to the current location. Why this need to preserve old links forever? Websites change. If we migrate from trac to something else, I'm not going back and updating every website that ever linked to trac. When we changed from flyspray to trac, google, yahoo, bing, etc search engines all update their databases of links within 3 days. I'm fine with not putting in any redirects. If the new structure is sufficiently logical, people will figure it out. torproject.org is the largest link farm to trac, we can update that. Attached is the linking domains, according to google, to trac.tpo. -- Andrew pgp key: 0x74ED336B
On 6/11/11 2:41 PM, andrew@torproject.org wrote:
On Sat, Jun 11, 2011 at 08:17:35AM +0200, karsten.loesing@gmx.net wrote 2.5K bytes in 34 lines about: : > Do you plan to fix links in the mailing list archives as well? How : > about links in our e-mail inboxes? : : Nope. But we could add redirects for those pages linked from the : mailing list archives and everyone's inbox. Similar to how we added : redirects when moving from : https://wiki.torproject.org/noreply/TheOnionRouter/ to the current location.
Why this need to preserve old links forever? Websites change. If we migrate from trac to something else, I'm not going back and updating every website that ever linked to trac. When we changed from flyspray to trac, google, yahoo, bing, etc search engines all update their databases of links within 3 days.
Okay, I don't feel strongly about this. I think if we can add redirects easily we should do that.
I'm fine with not putting in any redirects. If the new structure is sufficiently logical, people will figure it out. torproject.org is the largest link farm to trac, we can update that. Attached is the linking domains, according to google, to trac.tpo.
Great! Thanks for the info! Alright. I think there's no way to make everybody happy. But I believe the lesser pain is to have a better wiki structure than we have right now. I'm going to start moving around stuff soon. Best, Karsten
participants (4)
-
andrew＠torproject.org -
Jeroen Massar -
Karsten Loesing -
Robert Ransom