Slowly updating the Documentation

Alex has been copying the documentation from the website into the Wiki. The idea behind this is that the documentation on the website is partially dated and structured in a way that does not reflect the way new users come to MusicBrainz any more.

I have now joined him in his effort of RestructuringTheDocumentation. This is the second restructuring that this Wiki experiences (the first was the general RestructuringTheWiki).

I assume this to be a slow process. Alex has already wikified all the pages. Now we have to intertwingle them and then we will understand what needs correction and updating. When the docs are well intertwingled into the wiki, people will start to use the MusicBrainzDocumentation on the Wiki; that is they will post questions, summarize long texts, delete obsolete stuff etc. Hopefully after half a year or so, this will give us some fine new docs that we can then copy to the main server again.

Alex even hat the idea to add a Wiki markup interpreter to the server, so that updating the doc would then only mean to copy the markup from the Wiki to the server.

6 thoughts on “Slowly updating the Documentation”

  1. While I have converted quite a few pages into Wiki form, it’s far from all of them, as can be seen at the RestructuringTheDocumentation WikiPage.

  2. I’m glad you guys have taken on this project — I am grateful for all your hard work on this.

    But, I am still fundamentally bothered by the fact that we have two sets of docs and that we’re going to be copying them back and forth. Whenever you have two sets of docs they will get out of sync — invariably.

    Maybe we can have a cron job that copies them on a nightly basis. Or maybe we can create a main site like wiki-stylesheet so that we can present wiki-doc pages that don’t look like a wiki…

  3. I do not think duplication is an issue yet. The docs on the Wiki are quite in an awful state yet, and Alex did of course link to the original versions on the homepage.

    Most docs are not intertwingled, so nobody will find them anyway. I will add a status line at the top of all pages that have a duplicate on the main server.

    But I am not too afraid of duplication. Actually I hope that the pages Alex copied will be torn apart, merged, renamed and changed to the point where you cannot say “This is a duplicate of that” anymore.

  4. Even more than that, it should be possible to just have large parts of the documentation live *only* in the wiki. For maximum user comfort, this would probably require some tweaks to the wiki so that it can be inside the standard home frame as long as you’re just reading, not editing. Wiki pages wouldn’t have the fancy javascript tricks with the site menu (all the doc pages would just show Wiki) but the increased quality of the docs should be worth that small loss.

  5. Alex even hat the idea to add a Wiki markup interpreter to the server, so that updating the doc would then only mean to copy the markup from the Wiki to the server.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.