Mod Archive Forums
Music Production => MilkyTracker => Tracking => MilkyTracker Community => Topic started by: raina on April 22, 2008, 12:05:32
-
As some of you may have noticed the announcement on the documentation page (http://www.milkytracker.net/?documentation), 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 (http://wikkawiki.org/) but haven't decided yet.)
-
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.
-
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.
-
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.
-
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.
-
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!
-
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..?
-
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.
-
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?
-
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! :)
-
I am uploading my "skeleton document". It's not quite a skeleton because I couldn't resist filling half of it out. The problem that caused is that I delayed the release of it 10 months because I couldn't resist the urge to keep filling more in. I now have a better sense of why unpaid development is a slower process. ;)
I worry that this will be redundant with a document that's already been started. If so, hopefully they can be merged.
I'm will continue to work on the document. Hopefully crowdsourcing this work will help finish it off much faster than I am able to!
When it's finished I am excited to convert it into other formats such as html, pdf, lit, etc.
Note: The file is two zips. Unzipping will create two rars. Unrar will create the word document. Here is part 1.
-
Here is part 2.
-
thanks for sharing. i'm going to add a "pc platform" guide soon. i have already started some weeks ago ;D... but my approach is different from your skeleton-like.. hmm.. gimme some days to complete.. yeah!
-
New Version V.0.1.1
Includes table of contents
Reformatted
Now broken into two separate documents. This allows each half to be zipped and uploaded directly. No more extracting rars from zips and then extracting the doc from a rar. Now simply extract the doc from each zip and enjoy.
-
And part 2.
-
I'm still waiting for our good friend raina to get the wiki going. It would be awesome to have place where users can document and share tips and tricks for working with Milky.
By the way, I think an open, public, centralized location for the information needs to come first. Once users have submitted enough content it can be compiled into a portable document. Having to download or store on your HDD a copy of the document, edit it then re-upload it every time is too much trouble and I think will deter users from submitting content. It should be quick, easy and convenient like having a black board with chalk and erasers sitting and waiting to be written or drawn on. An administrator can be in charge of creating a portable document based on user submitted content to the website.
So let's get the wiki rolling, raina! Who knows? It might inspire you! :-)
Grifter
-
i looked at your document skeleton... it's a good effort. i just wish it were complete because i'm looking for full documentation, not looking to write it, hah hah. it's a hard thing to develop a tool, know it intimately, and then watch as people scratch their heads on what it is, how it works and what all the twiddly bits do. i've been a documentation writer for many tech projects in past. i was even a tech trainer as a career for a while. i've never been able to program, tho i get the concepts, so i went toward the user-oriented areas for "being useful."
why did you choose MS Word as the format for the file?
-
I chose MS Word format for the file because it's ubiquitous. It can be opened by all Windows users even if they don’t have MS Word, and can be opened by Linux users who have OpenOffice. I suspect that Mac users can also open the format. It is ideal that the document can be modified by all users of varying technical ability to allow it reach a finished status ASAP.
Once it’s completed, I will port it to more efficient formats such as PDF, HTML, MHT, CHM. Those formats are not as easy to edit for most users, and so I chose MS Word as the base document. I broke it into two parts because it’s image laden nature made it large, and this BBoard has file size limits on attachments that I needed to consider.
I haven’t put much work into it lately because it appears my platform is being abandoned for continued development. The 0.90.80 release for Windows Mobile has some difficult bugs in the Internal Browser that make it difficult to work with on the Pocket PC. These issues were announced as fixed by Pailes, but those code changes were never compiled into a release for Windows Mobile. :(
I can’t complain because it’s a free product and I understand that Pailes has to invest his time into things that actually pay the bills.
[Milkytracker is the main reason I value my pocketpc so highly. Without it I would probably get an android phone. I imagine that a port to Android would be a significant undertaking, and haven’t considered whether the UI on android would even be practical for such an app.]
-
good points.
on WinXP SP3, WordPad wont load the images in your document at all. i guess i'd have to install Open Office, but dunno if 500MHz with 133MHz bus can handle it... OO is kind of a beast.
too bad about the pocketpc port. i appreciate the loss of a favoured platform (esp when favoured due to software on it). i have the music apps made by http://www.chocopoolp.com and they're dead ended due to the platform being dead (great work there by the idiots in executive suits at Palm, totally wasting massive amounts of their developer's efforts after buying Be Inc. and hiring the Be developers... i had two insiders on that and they said they were too pained to talk more about it aside from "utter ABORTION" ... Palm abandoned it all for linux-based replacements because of PR memes... hell they don't even SELL a proper PDA any more). worse, since i stopped maintaining my Tapwave Zodiac as a portable device due to having an iphone, the Zodiac's battery is useless. the device requires being plugged in & it's now boxed up because of that limitation. being on disability with a fixed income means i can't spend money on "little" things like a replacement after market battery. sigh. there was/is another cross platform tracker that worked well on Palm OS called Psytex and its followup "Buzz like" tracker. my device was too underpowered for that followup app, but it was great having a little tracker/modplayer on my Zodiac. sigh...
-
I could never get psytex to run right on my Palm, and that was one of the things that motivated me to switch to Pocket PC after my Palm died.
I didn't know wordpad wouldn't load the images in the doc. You should be able to use a free online converter to convert the document to something you can read, such as pdf. (for example http://en.pdf24.org/)
Is there a format you'd prefer that can handle the images?
-
Is Rich Text (RTF) robust enough for your intentions? i tend to use that as my standard formatted text file format, but i know it has limitations.
which Palm device did you have and which version of PsyTex did you try? i think PsyTex II was the one i used.
-
RTF has robust enough formatting, but lacks the image compression that Word has. Saving the files in RTF format resulted in files that were 10 times larger. (which excludes them from being shared through this board.
I can email zipped versions of the files if you wish.
I think I had a Palm Vx. I can't remember the version of PsyTex. I know I had to install a hack for it to be able to "work" but still couldn't get it to run in any workable way.
-
Hey everyone, this is my first post here. It seems like this thread was abandoned and no wiki was established, so I took the liberty of creating a whole site running MediaWiki called MilkyDocs.com (http://MilkyDocs.com). Since the time this discussion originally took place (almost 10 years ago), Mediawiki has still remained the most popular open source wiki platform, so I went with that.
Here's the wiki. It's open to anyone to contribute, and I'd love to see it become the de facto place where people of all levels of experience go to learn more about making great music with MilkyTracker:
http://milkydocs.com/ (http://milkydocs.com/)
-
Just a thought, since it's a wiki it might make sense to not just put the whole manual into one big wiki page but put each chapter on its own page.
-
That's a large task (in terms of both organization and time investment). I do also wonder how much better it would be having the official manual spread out over multiple pages. People don't like to wait for pages to load so it's kind of nice (IMHO) when you know that you're looking at the official manual in its entirety on one page. We can still use wiki functionality to dive deeper on certain subjects and link from the official manual, or to just create new content entirely. That said, this is part of the beauty of the wiki being community maintained. Anyone can go in and start on adding, removing, reorganizing, or changing any of the content.