Page 3 of 7
Re: Official(?) MT 1.3 Documentation Project
Posted: Sun Feb 13, 2011 11:01 pm
by Azhrei
Welcome to the world of publishing. Or rather, cross-platform publishing.
Re: Official(?) MT 1.3 Documentation Project
Posted: Mon Feb 14, 2011 1:59 am
by scriptminion
Question: is the purpose of this project to document MapTool into a document that can be referenced that will potentially be distributed with the software, or is the purpose to solely document the features of MapTool? If it is the former, then I can understand the need for a Google doc file or some manner of collaborative document. If it is the latter, then would not the wiki be the best place for this information to reside?
Also, (and this is probably jumping the gun a bit) once this document is created, is there any plan to integrate the information into contextual help for the program (a la Microsoft HTML Help however, since this is Java-based, use, say, JavaHelp)?
Re: Official(?) MT 1.3 Documentation Project
Posted: Mon Feb 14, 2011 2:50 am
by wolph42
Azhrei wrote:Welcome to the world of publishing. Or rather, cross-platform publishing.
not helping Ahz...
Really, who's going to take the lead in this and what is the preferred way to go?
My personal favourite: open document accessible to all, let everyone cram in their part until you have a (very likely very ugly) base or 0 version, with different styles and layout. Then take the doc off-line, do the layout and general editing. Put it back and from then on use some method of control on the submissions, e.g. limit editors or use some track changes method.
The reason I like this is because you can get a 0 version pretty fast and even if you do it 'the right way' from the start, you'll have to do the layout later on anyway.
If we we're to take that strategy then the first step is just blatantly copy paste Wiki articles straight into the doc.
Scriptminion has a good point though, what
is the purpose?
Re: Official(?) MT 1.3 Documentation Project
Posted: Mon Feb 14, 2011 3:02 am
by CoveredInFish
wolph42 wrote:Azhrei wrote:My personal favourite: open document accessible to all, let everyone cram in their part until you have a (very likely very ugly) base or 0 version, with different styles and layout. Then take the doc off-line, do the layout and general editing. Put it back and from then on use some method of control on the submissions, e.g. limit editors or use some track changes method.
Agree. I'd say lets start this using the google docs file. If it has reasonable content I lock it and set the content in a prettified form (from here on I'll use latex). Then maybe we can use the SVN and work on the latex source files via subversion... or not, lets not overthink this at this state.
If we achieve this state we can publish pdf and html versions as well easily. A html version could be placed on the main rptools site. Maybe the docs could be "shipped" with a docs opdf/html, maybe it would be even reachable via help menu. I dont think that a real context sensitive help is necessary - and its more difficult to set up.
Re: Official(?) MT 1.3 Documentation Project
Posted: Mon Feb 14, 2011 4:06 am
by Craig
wolph42 wrote:Azhrei wrote:Welcome to the world of publishing. Or rather, cross-platform publishing.
not helping Ahz...
Really, who's going to take the lead in this and what is the preferred way to go?
My personal favourite: open document accessible to all, let everyone cram in their part until you have a (very likely very ugly) base or 0 version, with different styles and layout. Then take the doc off-line, do the layout and general editing. Put it back and from then on use some method of control on the submissions, e.g. limit editors or use some track changes method.
Not so sure about this. Word processors are awful when it comes to fixing format after the fact (actually they are not that great when you are formatting while you are going). If Fish is willing to latex it up then I would say just dump the text in google docs don't worry so much about the format and once its all done its much easier to make it all pretty using latex, and then you can even generate well formatted A4 and that other silly standard the US uses for paper
Keeping a consistant format on a word processor document being collaborated by multiple people is a disaster without a lot of discipline.
Re: Official(?) MT 1.3 Documentation Project
Posted: Mon Feb 14, 2011 4:16 am
by CoveredInFish
I thought thats what wolph meant: do not care about the layout - ah ... well ... maybe do a minimum to keep it readable. I'll do that in latex anyway (as I see several advantages versus word processing or even layouting suites like indesign like eg supporting several paper sizes, easy exporting to html, a world-class typography, ..).
So, contributers, your'e allowed to just dump in the content.
Re: Official(?) MT 1.3 Documentation Project
Posted: Mon Feb 14, 2011 6:11 am
by wolph42
CoveredInFish wrote:So, contributers, your'e allowed to just dump in the content.
ok done. Shortcut keys and chat commands are now part of the doc.
admittedly I couldn't help myself and did minor editing in a local word doc first. Mainly because the whole text was marked as Header 2.
As this is a topic where most experienced users can actually help us with, as this does not require e.g. heavy MT script or Java knowledge but just experience with MT... maybe its useful to broadcast the need for help over the forum by adding the following to your signature:
Code: Select all
[url=https://docs.google.com/document/d/1_a3B4GDMspyI5GFwgcr6zU1SDhYBrMP19P_hneUBYkE/edit?hl=en&authkey=CNmlv_gH][size=150][color=#FF0000][b]Help us with the MT Documentation project[/b][/color][/size][/url]
Which looks like this:
Re: Official(?) MT 1.3 Documentation Project
Posted: Mon Feb 14, 2011 11:56 am
by Azhrei
(Sorry guys, I'm only going to be able to check in here sporadically this week.)
I'd like the documentation to be a "User Guide". Something that someone new to MT can pick up and read as a sort of tutorial introduction to the tool.
However, I'm not going to complain if anyone puts together a Reference Guide either!
Re: Official(?) MT 1.3 Documentation Project
Posted: Mon Feb 14, 2011 7:09 pm
by aku
So, i did some formatting before i bothered reading any of the thread, and realized "we dont care"... lol. I guess i'll stop now, but i'll be happy do do the formatting at the end, since that seems to be the way people want to go, for now.
Re: Official(?) MT 1.3 Documentation Project
Posted: Tue Feb 15, 2011 3:05 am
by scriptminion
Well, in dabbling with the Google Doc a bit, I have gone ahead and put a rough skeleton with some information from the wiki to flesh out section 3.3 on MapTool Preferences. All of the embedded comments for this section are mine, too. Several of the different options' descriptions still need to be copied over from the wiki page, but the section is now started.
There are a couple of comments in the sections that are "completed" (as a rough draft goes) about when changes to any of the given settings actually take effect. If either a programmer or an experienced user can identify for me when that actually happens, I will go in and correct the sentences to read as they should.
Re: Official(?) MT 1.3 Documentation Project
Posted: Tue Feb 15, 2011 3:36 am
by wolph42
erm CIF, I was just looking at the doc and noticed that the 'google word' is in German, not really an issue for me but it might be for other users. And since I'm fairly certain that my language settings are english (or very unlikely Dutch) this means this is a result of settings you set.
Also I'm missing the export functions: Exporting Maps and Screenshots in the base structure.
Re: Official(?) MT 1.3 Documentation Project
Posted: Tue Feb 15, 2011 4:16 am
by CoveredInFish
My docs preferences are set to german but I thought I'd set this document to english.
That the UI is dependant on my settings is weird ... okay, i changed it to english again.
Okay, added "Exporting Maps and Screenshots "
Re: Official(?) MT 1.3 Documentation Project
Posted: Tue Feb 15, 2011 6:39 am
by wolph42
CoveredInFish wrote:My docs preferences are set to german but I thought I'd set this document to english.
That the UI is dependant on my settings is weird ... okay, i changed it to english again.
Okay, added "Exporting Maps and Screenshots "
nope still (or again) German. Might it have something todo with the hyperlink?
Edit: added 5.2.and 5.3 (bit of a pain to get screenshots into the doc, but after a while I got it). I don't get 5.4 (roll visibility option) after 5.3 Roll format options. 5.3 already covers 5.4 so it seems redundant.
Re: Official(?) MT 1.3 Documentation Project
Posted: Tue Feb 15, 2011 7:24 am
by Azinctus
I'm a professional editor and writer. I'm not sure how much time I could give to this project but I've taken a look at the Googledoc and I've made some minor, mostly cosmetic changes to the writing. I'll help more where and when I can.
Re: Official(?) MT 1.3 Documentation Project
Posted: Tue Feb 15, 2011 7:57 am
by CoveredInFish
@Azinctus:
Thats good news! Welcome.
@wolph:
Yes sir, it must be in the link. Now, with setting english, this link is shown in docs:
https://docs.google.com/document/d/1_a3 ... y=CNmlv_gH
and that differs from the one previously posted, that contains "hl=de"
We could probably differ between roll options that influence visibility and those which does not, but I agree that this isnt very intuitive. Probably we should join both sections into just one.