History talk:Restructuring The Documentation

From MusicBrainz Wiki

This is a discussion about the project of RestructuringTheDocumentation. It is about the goals of the project, how to do it, and any problems occuring.

The important bits are at the bottom after the double horizontal rule. If there are parts that we all agree on they should be moved up to the tentative summary.

Tentative summary

  • The rest is still controversial I believe.

Right now the best way to see the documents that have been wikified is to go to OriginalVersion and click on the title to see the BackLinks (this isn't ideal, and will be improved).  Most of the wikified documentation is dated, and it needs intertwingling badly. @alex 

Actually I have not really understood the system behind OriginalVersion. I have made an example of what I would do on AdvancedSearch, Is that ok? What about a page NeedsIntertwingling that would help with backlings and at the same time saying "This page NeedsIntertwingling" is pretty meaningful --DonRedman 

Your example is fine; I would perhaps avoid the use of "intertwingling" in WikiNames since it is long, and pretty jargony (like Karma, e.g.).  Maybe NeedsUpdating, NeedsLinking, and NeedsRevision or something like that? @alex 

All of the above (each where appropriate). We do not even need to create the pages at first. Just state: This page NeedsUpdating badly. I understand your concerns, but I like the word intertwingling. It is jargon, but it is wiki jargon. And it conveys a concept that wikizens should learn, so why not dedicate a page to it? --DonRedman 

Please stop blindly copying pages from the website to the wiki! Please discuss here first what the WikiName of the page should be, to which pages it should be linked, what other pages might have concurrent content etc. Please slow down the work.

HelpWanted and DevelopmentToDoList are examples of very bad dumping. They are not intertwingled with MusicBrainzDevelopment and their purpose is not well defined compared to FutureWork and CurrentWork --DonRedman

DevelopmentToDoList predates this effort by a month or more, so it's hard to blame to really blame Ruaok too much for this dumping. It does illustrate that it is very important to choose WikiNames carefully before replacing static content with links to the Wiki, since the static todo page links to that name, and cannot be changed easily. As for discussion on names, it's good, but just converting the HTML content to Wiki is work (I should know!) and we cannot object if somebody is willing to do the work of "blindly copying pages from the website to the wiki." Just be sure to mark it with a Status tag that indicates that it NeedsRenaming, to make sure it's moved to a better WikiName before linking to it. There's a lot of work to do, and I don't see any point asking people to "slow down."

Another important thing to keep in mind as you restructure the documentation is that the original static pages are linked to from other static pages (and even dynamic ones on the main site). That means that there no matter how much you may want to restructure the page, it still needs to work in that context. (Determining what that context is can be hard, it's true.) It also means that people who are totally unfamiliar with the concept of Wiki need to be able to read those initial pages without being thrown off by lots and lots of StrangeWikiNames or wiki-jargon like "intertwingling" -- it's also a reason to (eventually, not yet) move the Status stuff to the bottom of the pages.

I'm not saying we shouldn't intertwingle, or use wiki links, just that on the pages linked directly from the main content pages, we need to go easy, and make it more comprehensible to a Wiki-naive reader. If we can, they will explore the Wiki more, and learn about it. But the point of the documentation is explaining MusicBrainz, not explaining the Wiki. In that respect, these documentation pages are more like Wikipedia than like other Wikis (including this one); many readers of Wikipedia content do so on non-Wiki mirrors that are not even directly updatable -- similarly, when these pages are used to replace the existing static pages, they will probably use a simpler layout and interface, maybe something like the MoinMoin format=print option. @alex

OK, first sorry that I got this wrong. I did not want to blame anybody; especially not for submitting work to the wiki. I just started to be very confused about the sheer amount of pages

  • whose status is not clear
  • which partially have BadWikiNames
  • which are not intertwingled
  • which seem to be out of date.

And I was a bit afraid, that this was getting too much, hence my harsh tone. Again: I am sorry for that.

I still have two points. One is about GoodWikiStyle and I will try to give some good advice here. The other is about the goals of this project and we need to discuss this further (see below)

Good Wiki Style

From my experience of RestructureTheWiki I gathered a few points:

  • This means that if I believe a certain page sould be created, then I will say so (by writing the new WikiName) on as many related pages I can think of. This gives other people the possibility to (a) think of a better WikiName, (b) argue about the necessity of that page, and most importantly (c) make the page themselves (which spares me a lot of work). Also when that page is created, it will (d) already be intertwingled.
  • WaitAWeek:
  • I found that I could do changes to the wiki faster than the wiki could afford it. If I create a page, people have to use it (read it and make corrections). Only then will I know if there are any problems with the page (If the content is wrong/out of date, If the WikiName is bad because people refer to the page from another context than I thought etc). So I found out that it is a good thing to make links, WaitAWeek, create the page, wait another week, and then make corrections. But this only works if you MakeLinksBeforeMakingPages. Otherwise people will not find the page and thus not use it and thus I will never find out if the page is good or not.
  • I know that this is a controversial point between Alex and me. I wrote some lines about this on WikiNames. If a page starts to cover different topics, then the content cannot be referenced from other pages any more. A HTML sollution to this is anchors. But anchors destroy the link pattern of the wiki. So instead of making anchors I make a heading with a new WikiName and WaitAWeek. Hopefully someone will then already have moved the content to that new page.

Goals of Restructuring The Documentation

I believe that a possible outcome of RestructuringTheDocumentation is that the documentation gets restructured. By that I mean that it will get structured into different units than we currently find on the server. I believe that this is a good thing, because IMO the structure of the docs on the main server (and this includes the CurrentMenu) does not reflect the practice ot the common MusicBrainz user any more.

Thus I would deliberately let the documentation "run loose". I believe that by doing so we will get an idea of a better structure. Then when we have this idea, we can decide which pages should be mirrored on the server. If we tie the wiki pages to the outdated structure of the main server, then we will inhibit the natural reorganizing dynamic of the wiki.

I do not know how long such a process might take. I believe it will be something between three and nine months. That is ok as we are all amateurs doing this on our spare time. Also the outcome will not only be updated documentation but a system where keeping the docs up to date is easy. I believe it is worth the hassle. This means that IMO we should not replace static pages by wiki pages before the restructuring has finished. --DonRedman