Print

[raina]

As some of you may have noticed the announcement on the documentation page, we are looking to start a MilkyTracker user manual in wiki form. If you're experienced with wikis, I would like to hear suggestions (with reasoning) for a suitable platform because there seems to be a ton of options.

What we'd like it to be like is:

• W3C compliant like the rest of the site
• able to embed media
• preferably easily customizable so that it would  blend in with the site nicely
• simple
• light
• fast
• strawberry scented

and also, it should run on PHP/MySQL. So, if you do know a good wiki platform that matches most of this description, let's hear about it. (I'm currently looking at WikkaWiki but haven't decided yet.)

[maruchan]

Dokuwiki has worked well for me, but I use it on a very limited basis. It seems quite extendable if you want to do fancy things with media, like embedding a MOD/XM player or something.

[phire]

I've used dokuwiki,
Its very extensible, and it doesn't need a database (can be counted as both a good thing, and a bad thing)

But it might have scalability issues, and the default theme is horrible from a user interface design prescriptive, Takes me 5min to find the login link (somewhere near the bottom.)

But if your making your own theme, that shouldn't be a problem (remember, login link at the top right (top-center or top-left isn't that bad) of the page.

[DasKreestof]

Raina,
I was going to mention this on another thread, and I suppose it deserves it's own thread, but I'm going to mention it here anyway.

I am very grateful that Milkytracker has the amount of documentation that it has. It really has a lot for a free program in such a niche market. I respect the tremendous amount of work that has gone into creating and maintaining that documentation.

That said: As one can deduce from the forums, sometimes the documentation is lacking. Obviously someone has considered crowdsourcing to expand the documentation through a wiki.  I love wiki's but the downside of a wiki is that I can't keep the wiki on my PDA and read it on the airplane. (I was excited to be using Milkytracker on a plane this weekend)

In leau of a wiki, perhaps a skeleton document could be created, one that could be uploaded to the site. Crowdsource contributors could copy and paste updated sections to this site or perhaps mail contributions to a gmail address. Then you as the official maintainer of the manual could update the official manual through copy and pasting.  If that idea is bad, it could be a manual addendum.

I realize that this only works if people actually contribute. I realize that's rare, and that talk is cheap. There's a big difference between wanting to volunteer, and uploading finished work.  I know I would like to help. But I also know that I am frequently over reaching the limits of what my schedule will allow.

Anyway, what I would add to the manual is:
A chapter listing the differences between the Pocket PC version and the full version. (which isn't many)
A chapter broken down by section of each page of Milkytracker. Each section documenting all features of each page.
I realize this is a huge job, and will create a huge manual. But if the crowd steps up to the job, it's becomes a much easier task.  It will also allow many questions about undocumented features to be answered with RTFM!

Does this make sense?
For example - The boost function doesn't just boost the amplitude of a waveform, it also alters it's EQ right?  This kind of documentation of a feature can result in creativity. (I believe I learned about that in one of the tutorial videos.)

If you think this is a good idea, perhaps I will start on creating a skeleton addendum document. That way my idea is a way of volunteering you to do more work.

[raina]

Good input. And definitely deserving its own thread, if there already wasn't a perfect one for it. So, here you go, welcome to the user's guide thread.

I fully get your point about the limited portability of a wiki. Originally when I thought about doing this thing in wiki form, I was not only thinking about contributors but how the modular structure (BS for bite size articles) and simple editing would inspire myself to write a better and more comprehensive manual. While it still sounds tempting, I'll have to take our point into consideration and maybe steer away from wikis OR find one where it is easy to create and download snapshots to go.

[DasKreestof]

There are a lot of pros and cons to wikis. I'm obviously a fan of them since I joined the forum to ask people help flesh out the resurrected Milkytracker entry I added to wikipedia.

The biggest pro is that it might encourage crowdsourcing the work in a way that no other method will. It's also nice that it can help BS the work as you put it.

The biggest downside IMHO is the lack of portability.  This affects me in two ways. One, I can't access it when I need it when I'm offline. (and that's frequent) Two, that the wiki won't be around forever.  I have a lot of trouble getting information about equipment and software that I got 10 years ago that only had information online in a fashion that wasn't downloadable.  I have seen wikis vanish after mere months, and sometimes they were the only source of info. (example: an IPTV show on electronics, put all the show notes and schematics on in their wiki. I still have the shows, but their wiki is gone making the show projects impossible.)

I suppose someone could copy and paste all the wiki articles into a single downloadable document, but obviously that's a lot of work to assign to someone.

I don't know how to setup a wiki server, but I do know how to put together a document.
I love Milkytracker. I want to contribute to it. If it had been programmed in BASIC on an Apple IIe I'd be all over it's source code.  But since it's written in C and my C skills are only slightly above null, the way I can contribute is I can help flesh out more documentation.
I've started a skeleton document, sort of like a FAQ with sections to be filled in later.  I will plagerize the FAQ and some threads for some info, and when I think it's in a non-embarassing form I'll either upload here or send it to you.
My suggestion from there is: We break it down into tiny sections that people can download/fill out-expand upon/and then send back.
You as the maintainer of the official manual can then decide whether to include the new chapters in the official manual or keep them as an addendum.

I am hoping that I actually get this done and all of this isn't a bunch of talk and promise!

[raina]

A well organized standalone document in tiny sections (like you say) would probably work just as well. And the community isn't too big or complex for the crowd to get involved either. Is there a real-time way of getting in touch with you, IRC, MSN..?

[DasKreestof]

I have a bunch of instant messengers, but honestly I only log in to them a few times a year. Email is the best bet. Send me an email at misterfun at optonline dot net and I'll send you a reply from my real email address.

[klez]

about the issue on vanishing wikis, what about making a regular backup of the wiki's db so in case of death of the wiki one can still obtain it, recreate a copy on its hard drive and then reformat it as a 'standalone' documentation?

[DasKreestof]

I appreciate your suggestion Klez. When a MilkyTracker wiki does come to be, I do hope that a downloadable db is also available.

It sounds like a tricky feat. Here's why:
1. Wiki's I believe are usually run as SQL or MySQL server backends to a PHP or Asp front end.  That means that the db backup would likely have to be done offline for it to be done simply. A live sql server can be backed up while it's online, but in my experience that frequently requires costly applications. (Granted my SQL experience is limited.)

2. Wiki's that have downloadable backups of the database that are regularly created for end users to download tend to be rare in my experience. (Wikipedia does allow you to download theirs)

3. Converting said DB to a format presentable as standalone documentation may frequently be an incredible and time consuming feat.

4. I never know that a wiki might or is going to vanish until it is too late.  This is why it's incredibly ideal to have a document/manual that is included with software package.  Years later, the manual is still located in the download or extraction of the program, easy to find and not requiring hours of labor to answer the simple question of "How porous paste works" or something.

See here's the thing. I'm old and I'm stubborn. I will use a software package from 15 or even 25 years ago. (I recently replayed Zork)  I don't know if you've ever tried to find info or documentation about software from 10+ years ago, but trust me, it's usually vanished off the face of the earth.  The company is usually gone, and if it's not, anyone familiar with that product usually is. The answer you'll get is "buy the new supported product" regardless of whether it performs some obscure function of the old product that's made you keep it around, and regardless of whether it's compatible with the rest of your operating environment.

I'll restate: I like wiki's. I really do. But as a computer scientist/engineer I've came up with a saying: "Never put a computer in a position where a light switch would do." It's a way of illustrating the concept of KISS or (Keep it Simple stupid!) A small efficient html or even a bloated pdf is a fantastic resource to include with the Milkytracker package.  It's viewable on a PocketPC (which I use Milkytracker on) and by having a copy I know I can read it as long as I have something that will run milkytracker, regardless of whether I have Internet access or if the wiki still exists.

Wiki editing might be more inviting to geeks, but it's also harder and requires learning another code base.  The method I suggested above requires only simple document editing abilities, to later be cleaned up by someone and parsed into an efficient document. It also doesn't require anyone to learn how to build a wiki server and can be done quickly and easily.

Putting my money (or in this case time) where my mouth is: I have started the skeleton document and should be able to upload it in the near future. I have taken most of the screen captures necessary from the PC version, filled out a rough structure, and even filled in some parts already.  At current the skeleton document is a word document at 790kb. It's bloated but simple to work with at current.  I will convert it to html, and parse it down to HTML 3 standards for very simple and easy to manipulate code.  This will make it easier for Raina to convert to a CSS style addition or addendum to the manual later.
It is likely that in it's work phase we'll keep in the .doc format because most people can read and write that format and it's relatively easy to convert from that format to one that is more ideal for distribution of a read only document. (less people can edit an html or pdf document than a .doc)
I think raina had a good idea about breaking the document into smaller parts for updating. It may prevent people from doing overlapping work, and by breaking it into smaller steps it might make the job seem more appealing and less taunting to contributors.

I don't know what the ideal way is to crowdsource working on the document is. I appreciate the fact that a wiki would be the easiest way. But this is something we can get done now, and will have the advantages outlined above.  If I had a public IP I would donate a server to the cause. But I don't

BTW: If there's a simple way to convert/view/reformat wiki databases on a desktop and pocketpc, I'd love to here about it!