Thank you...we'll definitely need that!brad wrote:I would be willing to make some manual or wiki specific videos. If there is a specific topic or action that would lend itself to some clarification, I could make a mini(30 second to 2 minute) video that the docs could link to. That way there wouldn't have to be a link to one of my tutorials that is 4 to 7 minutes long and covers some stuff you were not addressing. A quick and to that one point that you are addressing, video. If you think that sort of thing would be more useful then just linking to my normal tutorials, I am up for it.Azhrei wrote: Using MediaWiki might be nice in a couple of regards, as I think Brad's videos should be linked from the docs, but there's no reason that a regular wiki can't link to them as well.
Let's write a manual ! [help wanted]
Moderators: dorpond, trevor, Azhrei
0+0=1, for very unstable CPUs.
That would be awesome, Brad. We do something similar to that here at our office, and it is an absolute hit with our users. And with tech services because it gives the advantage of one of us logging into the user's system for a moment and showing them by example. Which is a wonderful teaching tool, but tends to be inefficient for something that only takes a click or two...like say, showing a user how to turn on their BCC field in Outlook.brad wrote:If there is a specific topic or action that would lend itself to some clarification, I could make a mini(30 second to 2 minute) video that the docs could link to. That way there wouldn't have to be a link to one of my tutorials that is 4 to 7 minutes long and covers some stuff you were not addressing. A quick and to that one point that you are addressing, video.
When I first started using maptools, your videos were probably the best instruction I got and I referred to them several times (thanks!), but very often I was skipping around through them looking for the part where you mentioned such and such because I just wanted that one little piece shown to me again. So I for one see a great value in having tiny encapsulated lessons.
El Cucuy
Excellent point.ElCucuy wrote:That would be awesome, Brad. We do something similar to that here at our office, and it is an absolute hit with our users. And with tech services because it gives the advantage of one of us logging into the user's system for a moment and showing them by example. Which is a wonderful teaching tool, but tends to be inefficient for something that only takes a click or two...like say, showing a user how to turn on their BCC field in Outlook.brad wrote:If there is a specific topic or action that would lend itself to some clarification, I could make a mini(30 second to 2 minute) video that the docs could link to. That way there wouldn't have to be a link to one of my tutorials that is 4 to 7 minutes long and covers some stuff you were not addressing. A quick and to that one point that you are addressing, video.
When I first started using maptools, your videos were probably the best instruction I got and I referred to them several times (thanks!), but very often I was skipping around through them looking for the part where you mentioned such and such because I just wanted that one little piece shown to me again. So I for one see a great value in having tiny encapsulated lessons.
El Cucuy
0+0=1, for very unstable CPUs.
And I think it goes without saying that once such videos are available, the manual should include hyperlinks to the relevant tutorials, which ideally would just load up in the browser and start playing. (In the beginning of the vids, I'd also place the address of the download site for those who wish to download the vids for offline viewing.) These links could also be included in the wiki in various places.
Orchard: Regarding my wiki, should I post it here in the thread or PM people who want to have a look? (I'd PM you right now, but I don't have the wiki on me.)
Orchard: Regarding my wiki, should I post it here in the thread or PM people who want to have a look? (I'd PM you right now, but I don't have the wiki on me.)
Just PM the relevant folks--myself & bigO for starters. We'll move from there. I'd like to take a look, but frankly want a chance to map things out before we get people leaning toward one style or another. I find that if a bunch of people start seeing a style then they make decisions about that style (love it/hate it) before they have a good chance to think about the full needs and requirements. No slight to you in anyway, I hope, but I really want to map out more of the project before we get going. Some recent experiences have lent me some insight on that process.plothos wrote:And I think it goes without saying that once such videos are available, the manual should include hyperlinks to the relevant tutorials, which ideally would just load up in the browser and start playing. (In the beginning of the vids, I'd also place the address of the download site for those who wish to download the vids for offline viewing.) These links could also be included in the wiki in various places.
Orchard: Regarding my wiki, should I post it here in the thread or PM people who want to have a look? (I'd PM you right now, but I don't have the wiki on me.)
0+0=1, for very unstable CPUs.
Because I have it on good authority that certain folks don't like dokuwiki?BigO wrote:This might be a stupid question but RPTools already has a documentation wiki. Why would we start a new one rather than use the one we already have?
Or because we need to evaluate the utility of the tool for the wiki and for the manual compilation before settling on what's available just because it's handy?
I'm all for convenience--when it doesn't make the job 3x harder.
That said...it's a good point.
I suspect wiki products are like fora software--they all suck in someway, its just a matter of which ones suck the least.
0+0=1, for very unstable CPUs.
Ref: Using the existing DokuWiki
I don't want to start a long discussion of pros/cons on the plethora of wiki options so that said I'll be as basic as possible.
DokuWiki was created out of a need for an API documentation system (by programmers for programmers) and I feel strongly that we would run into its limitations sooner rather than later for this project. That said, I also don't think that the current Doku wiki that is provided on the rptools server would meet even a minimum set of user-friendly requirements.
There's a large number of wiki packages out there, so many that we could spend a good many weeks just discussing them all. In the end it will likely come down to personal preference.
If people want, I would be willing to start a thread to try and come to a group consensus on which wiki package should be used. However, if people want to take it on faith, I feel confident that MediaWiki will end up winning for no other than it is tried and true (as is evident of the success of wikipedia).
I don't want to start a long discussion of pros/cons on the plethora of wiki options so that said I'll be as basic as possible.
DokuWiki was created out of a need for an API documentation system (by programmers for programmers) and I feel strongly that we would run into its limitations sooner rather than later for this project. That said, I also don't think that the current Doku wiki that is provided on the rptools server would meet even a minimum set of user-friendly requirements.
There's a large number of wiki packages out there, so many that we could spend a good many weeks just discussing them all. In the end it will likely come down to personal preference.
If people want, I would be willing to start a thread to try and come to a group consensus on which wiki package should be used. However, if people want to take it on faith, I feel confident that MediaWiki will end up winning for no other than it is tried and true (as is evident of the success of wikipedia).
Last edited by leviat on Mon Oct 06, 2008 9:40 pm, edited 1 time in total.
Leviat, I'm not really all that partial to any particular wiki--I've got so little experience with actually running ANY wiki, that they all look the same from where I sit. Give me time to digest stuff.leviat wrote:Ref: Using the existing DokuWiki
I don't want to start a long discussion of pros/cons on the plethora of wiki options so that said I'll be as basic as possible.
DokuWiki was created out of a need for an API documentation system (by programmers for programmers) and I feel strongly that we would run into its limitations sooner rather than later for this project.That said, I also don't think that the current Doku wiki that is provided on the rptools server would meet even a minimum set of user-friendly requirements.
There's a large number of wiki packages out there, so many that we could spend a good many weeks just discussing them all. In the end it will likely come down to personal preference.
If people want, I would be willing to start a thread to try and come to a group consensus on which wiki package should be used. However, if people want to take it on faith, I feel pretty sure that MediaWiki will end up winning for no other than it is tried and true (as is evident of the success of wikipedia).
That said--mediawiki is good, but what we end up using will be largely determined by a few other factors. I need to hear back about a few other things, then I'll get back to you on that. If you could PM me with more details about what you see as the limitations of what you percieve to be the biggest 3-4 wikis, I'd really appreciate it. That alone would be a big contribution.
0+0=1, for very unstable CPUs.
I say a wiki is the way to go for this project.
A manual is a linear product, sure. But a wiki is useful for the WRITING stage.
It lets people just do the pages they're working on, and that's that. It's online editing with version history, so it's portable. Syntax is quirky but livable.
Most good wikis have lovely organizational tools built right in, like categorizing and page ToC generation.
Easiest way for multiple people to contribute to the same page-topic.
And once it's done, you can just export the pages into a linear manual.
Finally, do we need a full self-hosted wiki engine? Wikidot works quite well, would handle all the hosting and such and is free.
A manual is a linear product, sure. But a wiki is useful for the WRITING stage.
It lets people just do the pages they're working on, and that's that. It's online editing with version history, so it's portable. Syntax is quirky but livable.
Most good wikis have lovely organizational tools built right in, like categorizing and page ToC generation.
Easiest way for multiple people to contribute to the same page-topic.
And once it's done, you can just export the pages into a linear manual.
Finally, do we need a full self-hosted wiki engine? Wikidot works quite well, would handle all the hosting and such and is free.
I'm hashing out the details of what we need--and those are excellent points.palmer wrote:I say a wiki is the way to go for this project.
A manual is a linear product, sure. But a wiki is useful for the WRITING stage.
It lets people just do the pages they're working on, and that's that. It's online editing with version history, so it's portable. Syntax is quirky but livable.
Most good wikis have lovely organizational tools built right in, like categorizing and page ToC generation.
Easiest way for multiple people to contribute to the same page-topic.
And once it's done, you can just export the pages into a linear manual.
Finally, do we need a full self-hosted wiki engine? Wikidot works quite well, would handle all the hosting and such and is free.
I spent some time last night (while watching Smallville & Supernatural--great shows!) looking at a comparison of various wikis. Several stood out above the rest, but I'm certainly not at the point to make any sort of decision.
At this point it's a given, I think, to use the wiki for creating, editing and even maintaining the majority of the documentation.
0+0=1, for very unstable CPUs.
Thank you for the suggestion. I'll check into that.Phergus wrote:RPTools already uses Atlassian's JIRA for bug tracking. Their Confluence wiki package is very nice and I believe it is also free for open source projects. Supports export to PDF and Word doc. Has WYSIWYG editing and wiki markup plus a ton of Confluence specific features.
0+0=1, for very unstable CPUs.
Just a stray thought on the manual (assuming this is still being thought about):
This thread (http://forums.rptools.net/viewtopic.php?p=66315#66315) made me think that it'd be a good idea to have a hints and tips section as a separate part of the manual. No doubt some of that will come out in the descriptions of the functions and such, but a categorized hint section would be a great addition. Hints on how to do macros, hints on how to deal with doors, hints on how to keep memory usage down, hints on how to run encounters, etc. would all be places newer players (and vets) could go for help. The forums are here, of course, but this would be instantaneous, would expose issues one might not have even thought of before (like the cracked door thing), and would be more portable.
Don't know if this was a given or what, but seems a good way to go.
This thread (http://forums.rptools.net/viewtopic.php?p=66315#66315) made me think that it'd be a good idea to have a hints and tips section as a separate part of the manual. No doubt some of that will come out in the descriptions of the functions and such, but a categorized hint section would be a great addition. Hints on how to do macros, hints on how to deal with doors, hints on how to keep memory usage down, hints on how to run encounters, etc. would all be places newer players (and vets) could go for help. The forums are here, of course, but this would be instantaneous, would expose issues one might not have even thought of before (like the cracked door thing), and would be more portable.
Don't know if this was a given or what, but seems a good way to go.
Yes, it's still under consideration.plothos wrote:Just a stray thought on the manual (assuming this is still being thought about):
This thread (http://forums.rptools.net/viewtopic.php?p=66315#66315) made me think that it'd be a good idea to have a hints and tips section as a separate part of the manual. No doubt some of that will come out in the descriptions of the functions and such, but a categorized hint section would be a great addition. Hints on how to do macros, hints on how to deal with doors, hints on how to keep memory usage down, hints on how to run encounters, etc. would all be places newer players (and vets) could go for help. The forums are here, of course, but this would be instantaneous, would expose issues one might not have even thought of before (like the cracked door thing), and would be more portable.
Don't know if this was a given or what, but seems a good way to go.
I got really busy with work, and so I haven't had time to look at this very much in the past few days. Sorry about that. Then my son had a bday, and, well, bluntly put, RL happened. Commas too.
Urk.
Here's where we stand:
We have a good number of willing folks. This is excellent.
The plan looks like a wiki + manual. I like this approach. I am also going to suggest a .chm for the macros and the accessible objects that can be attached to maptool itself. These types of manuals are helpful. Maybe not .chm particularly, but definitely a help manual that is very restricted to quick-reference topics like macros, operators, chat commands and dice rolling. More advance stuff would be referenced to the wiki, I think.
Overall, I think this is a solid plan.
Sections to go in the wiki are adaptable. I say that if people want to start writing sections that they feel are appropriate, then I would encourage that. I will begin working off given outlines and post an expanded list of needed areas in the next week. I expect that this will take some time. A quality manual will take some time to build. With any luck, if we start now, we should be able to have some good content ready to go live about the time 1.3 is finalized.
0+0=1, for very unstable CPUs.