Official(?) MT 1.3 Documentation Project

Doc requests, organization, and submissions

Moderators: Azhrei, dorpond, trevor

User avatar
CoveredInFish
Demigod
Posts: 3104
Joined: Mon Jun 29, 2009 10:37 am
Location: Germany
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by CoveredInFish »

Yeah, I love to hear that. Awesome.

Myself I've far less time at hands to bring this project along todays but I keep watching with interest.

And I'll keep my promise to set up a LaTeX document from the google doc once its "completed", so we have a well set pdf.

User avatar
mjn
Kobold
Posts: 13
Joined: Tue Feb 21, 2012 8:43 am
Location: Ithaca, NY
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by mjn »

Why do you think it is important to format it in LaTex? Granted, it has nice index generation, but I would think it better to get the formatting as good as we can make it in Google Doc and publish it in PDF.

- Mark

User avatar
mjn
Kobold
Posts: 13
Joined: Tue Feb 21, 2012 8:43 am
Location: Ithaca, NY
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by mjn »

I made some substantial changes to the document this morning. These include:

1. Added a Things to Do table at the very top.
2. Added a Document History table at the end.
3. Adding an Authors table at the end.
4. Reformatted Section 6 - fonts, white space, lists, etc.
5. Reformatted Section 7 - fonts, white space, lists, etc.

I am proposing the following changes/improvement as well:

1. Remove line numbers from macro listings.
2. Regularize the styles used to show results in chat, macro listings, etc.
3. Add section numbering to Chat (S6) and Macros (S7).

After making a complete pass over the document in terms of formatting, initial content, image improvement, and the like, I am planning on doing a detailed read through and apply the instructions back into MapTool to see how consistent they are and note where improvements might be made. Following that, I'd like to call on some of the MT experts to review the document for accuracy, clarity, usefulness, etc. and get any suggests they might have.

In my opinion, the document is not all that far from being usable. It still needs clean up and there is some key content still missing, but with those resolved, folks could start using it.

- Mark

User avatar
Azhrei
Site Admin
Posts: 12050
Joined: Mon Jun 12, 2006 1:20 pm
Location: Tampa, FL

Re: Official(?) MT 1.3 Documentation Project

Post by Azhrei »

mjn wrote:2. Regularize the styles used to show results in chat, macro listings, etc.

That's pretty important -- thanks.

It helps significantly to have a consistent set of styles to use, and creating a style named "Chat" and using it for everything that appears in the chat window, for instance, is much preferred over using individual font attributes (font name, style, and so on).

User avatar
CoveredInFish
Demigod
Posts: 3104
Joined: Mon Jun 29, 2009 10:37 am
Location: Germany
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by CoveredInFish »

mjn wrote:Why do you think it is important to format it in LaTex? Granted, it has nice index generation, but I would think it better to get the formatting as good as we can make it in Google Doc and publish it in PDF.


Important? Maybe not. Much more important I believe is to have good content. And a well formatted google doc might suffice at all.

But I really think that it is really hard to get some good, "professional" typography with google docs - while its pretty much automatically done in LaTeX. Second I believe that it is really easy to maintain larger projects with LaTeX - editing, making additions, etc wont destroy your layout (since its generated when needed). Last O think its nice that you can create different page formats from (almost) the same source.

But for getting it done it doesnt matter if I try to publish this thing in LaTeX later, it has to be (almost) finished first. It even does help if it is formatted consistently for that process. So it is totally good to create a good looking GD we could live with - and have my LaTeX idea an optional thing. :)

BTW I only quickly skimmed the doc, but I like what you've done so far.

User avatar
mjn
Kobold
Posts: 13
Joined: Tue Feb 21, 2012 8:43 am
Location: Ithaca, NY
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by mjn »

Azhrei wrote: It helps significantly to have a consistent set of styles to use, and creating a style named "Chat" and using it for everything that appears in the chat window, for instance, is much preferred over using individual font attributes (font name, style, and so on).


Not sure how to do that in GD, but I'll figure it out. It seems to have a copy/paste style feature, perhaps I can save a style and name it.

- Mark

User avatar
mjn
Kobold
Posts: 13
Joined: Tue Feb 21, 2012 8:43 am
Location: Ithaca, NY
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by mjn »

CoveredInFish wrote:But I really think that it is really hard to get some good, "professional" typography with google docs - while its pretty much automatically done in LaTeX. Second I believe that it is really easy to maintain larger projects with LaTeX - editing, making additions, etc wont destroy your layout (since its generated when needed). Last O think its nice that you can create different page formats from (almost) the same source.


I do see your point. Let's hold of on that until we have a document that we think is worth the effort to convert it to LaTeX. I've never worked with it, personally, though I've certainly heard of it. I'm not convinced that maintaining the document in LaTeX would be better than keeping it in GD.

CoveredInFish wrote:BTW I only quickly skimmed the doc, but I like what you've done so far.


Thank you. If you have suggestions, I'm open to hearing them.

- Mark

User avatar
CoveredInFish
Demigod
Posts: 3104
Joined: Mon Jun 29, 2009 10:37 am
Location: Germany
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by CoveredInFish »

mjn wrote:Let's hold of on that until we have a document that we think is worth the effort to convert it to LaTeX. I've never worked with it, personally, though I've certainly heard of it. I'm not convinced that maintaining the document in LaTeX would be better than keeping it in GD.


Yes, waiting I will.

Maintaining might not be easier - a WYSIWIG editor like GD (with its web interface and sharing features) is an awesome tool. LaTeX is mark up hell and to work with a team on it you'd have to use a VCS like svn - but once the document is set up the contributors only have to use very simple mark up, some of it makes even sense when you read it the first time.

What IS easier to maintain is indexes, links, references, table of content and such stuff. But this project might not be one that needs these features so much.

I guess I should wait for some pretty final version :-D

User avatar
mjn
Kobold
Posts: 13
Joined: Tue Feb 21, 2012 8:43 am
Location: Ithaca, NY
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by mjn »

CoveredInFish wrote:Maintaining might not be easier - a WYSIWIG editor like GD (with its web interface and sharing features) is an awesome tool. LaTeX is mark up hell and to work with a team on it you'd have to use a VCS like svn - but once the document is set up the contributors only have to use very simple mark up, some of it makes even sense when you read it the first time.

What IS easier to maintain is indexes, links, references, table of content and such stuff. But this project might not be one that needs these features so much.

I guess I should wait for some pretty final version :-D


Ok, I think we are in general agreement then. I have nothing against LaTeX personally, but I'm not really interested in learning yet another markup language having been through nroff/troff, html, and any number of wiki systems.

Work is progressing steadily with the clean up. I've made passes on the frames and macro sections. They are better, though perhaps not final. Mostly, I'm trying to get the whole document into a consistent format/style. Once that this done, I'll be focused on the content itself: does it meet needs? it's it clear? are the examples and illustrations good? Etc. I may need help with that, since I cannot consider myself an MT expert. I'll post content questions here.

- Mark

User avatar
CoveredInFish
Demigod
Posts: 3104
Joined: Mon Jun 29, 2009 10:37 am
Location: Germany
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by CoveredInFish »

The community is great, helpful and responsive and I guess I can name some guys around here we can ask specific stuff I dont know.
I dont fear questions :-)

Great you bring momentum!

User avatar
CoveredInFish
Demigod
Posts: 3104
Joined: Mon Jun 29, 2009 10:37 am
Location: Germany
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by CoveredInFish »

I started slowly (time is limited) to convert the google doc to latex.

A sneak preview here: https://dl.dropbox.com/u/1821838/mtdocs.pdf

Any feedback?

@mjn: are you still working on this? I havent noted any recent changes. If you did I would begin with chapters marked as "complete".

User avatar
wolph42
Deity
Posts: 9703
Joined: Fri Mar 20, 2009 5:40 am
Location: Netherlands
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by wolph42 »

CoveredInFish wrote:I started slowly (time is limited) to convert the google doc to latex.

A sneak preview here: https://dl.dropbox.com/u/1821838/mtdocs.pdf

Any feedback?

@mjn: are you still working on this? I havent noted any recent changes. If you did I would begin with chapters marked as "complete".


Nice, good work. I would suggest a slighly less ridiculously large (and typical TeX) margin.

User avatar
CoveredInFish
Demigod
Posts: 3104
Joined: Mon Jun 29, 2009 10:37 am
Location: Germany
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by CoveredInFish »

Hmm ... I tend to prefer bigger margins for print, but for screen reading I like smaller ones. Assuming this doc will be rarely printed I guess I look into that.

User avatar
wolph42
Deity
Posts: 9703
Joined: Fri Mar 20, 2009 5:40 am
Location: Netherlands
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by wolph42 »

CoveredInFish wrote:Hmm ... I tend to prefer bigger margins for print, but for screen reading I like smaller ones. Assuming this doc will be rarely printed I guess I look into that.


ok that's funny. I would reason exactly the other way round (but still find the margins way to big).

User avatar
CoveredInFish
Demigod
Posts: 3104
Joined: Mon Jun 29, 2009 10:37 am
Location: Germany
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by CoveredInFish »

Funny indeed :-) at last its a matter of taste. I dont want to go in details of line length and character count and how wonderful empty spaces are for your design ... it doesnt matter much here and were talking about a technical documentation.

I made some changes and I think its okay now. (updated the link above)

Post Reply

Return to “Documentation Requests/Discussion”