Jump to content
MandelSoft

NAM Documentation Online

31 posts in this topic Last Reply

Recommended Posts

Hello fellow SimCity 4 players!
 
Here's the online version of the NAM Documentation. This documentation is included in the NAM 31.2 too, but if you don't have access to the documentation for any reason, you can check out the manuals here.
 
The following NAM manuals are available in PDF format:

(Last updated: 2013-08-15, NAM 31.2)

NOTE: The NAM 32 PR1 is NOT documented yet.

Best,
Maarten

Share this post


Link to post
Share on other sites

Sorry guys, but I believe the "NWM manual" downloads the standard "NAM manual" and I am after the NWM manual. Don't mean to be a pain because I know it comes with the NAM download, but for what ever reason I do not have it anymore. Just thought it was worth mentioning. Oh and could I take this chance to say... WOW!!!   All of you guys are awesome. 

Share this post


Link to post
Share on other sites

Is a version for NAM 32 up yet? When I last downloaded my copy, I wasn't able to find an up to date manual during extraction processes.

HA! I thought it was just me. I even reinstalled NAM32 and was pulling my hair out because all the documentation says NAM 31.2! I was specifically looking for documentation on the nifty new RHW pieces... Oh well, I'll just play around with it on a blank city until I exhaust myself. :thumb:

Share this post


Link to post
Share on other sites

As I said above, documentation creation is one of the deadliest things any programmer has ever tackled.  I used to hate it, but if you are dealing with a paying customer and it is part of the contract, it has to be done.

Share this post


Link to post
Share on other sites

Yeah, no worries. Like I said, I was just relieved to find out I didn't do something bone-headed or was looking right at it and not seeing it. (like happens in a store- when you call the clerk and they go right to where you were standing and it was right. in. front. of. you!) :lol:

Share this post


Link to post
Share on other sites

Documentation has indeed fallen behind.  It's a lot to type and format and revise and add screenshots.  I think the main new things in NAM 32 are QuickChange and all the Flex ramps.  Both are pretty straightforward.  For the flex ramps you just plop 'em and drag RHW of any width through to override them.  QuickChange is just some prefab RHW stuff, to make building interchanges faster.

Share this post


Link to post
Share on other sites

I suggest that documentation for NAM 32 is probably a lost cause.  If anyone is working on documentation the effort might better be aimed at NAM 33 or 34.

Share this post


Link to post
Share on other sites

We really don't know what is going to happen with the documentation side of things right now, especially as we are short-staffed compared to how we used to be (and are likely to remain that way).  The documentation for the NAM 31.x releases was largely done by Ganaram and MandelSoft, the latter of whom has moved onto other games.  There won't be any specifically-labeled NAM 32 documentation, and right now, the priority is to get NAM 33 crystallized into a public pre-release, as it's been almost 16 months since NAM 32 was released. 

 

The new documentation format that was figured out for NAM 31.x, while producing a nice product, has proven to be very unwieldy to edit and update--the raw files are 130-page Word documents laced with tons of images.  I'd be happy to edit them myself, but I can't even open the documents without a CTD in either my browser (using the Google Drive version) or OpenOffice (using the saved files locally).  If NAM 33 is to be documented, we may end up having to start over from scratch, which, with our resources, isn't really feasible.

 

-Tarkus

Share this post


Link to post
Share on other sites

Good luck.  A simple release document usually is too technical for most users or too obscure.  I believe the team may very well have backed itself into a corner then painted the floor with hydrofluoric acid.  Initially the documentation was great, but using one of the standard word processors may not be the way to go.

 

In the past, I generally have used a programmable text editor (roff for example) to create this kind of documentation.  At the time, I don't believe it was possible and certainly not easy to insert images.  An alternative might be a good HTML editor such as Bluefish.

 

Look forward to seeing something by NAM 34.  This kind of thing is best handled by a technical writer than an implementing programmer.

Share this post


Link to post
Share on other sites
  • Original Poster
  • We used to have HTML-based documents. The trouble with those was that images could not be embedded and results may vary across systems. We went for the PDF approach, which seemed like a good approach at the time, but the Word files quickly became unwieldy, as Tarkus describes. Moreover, the NAM's complexity is ever-increasing and the documentation just can't keep up with that at the current rate people write documentation anyway. We really need more people dedicated to documentation in the NAM...

    Share this post


    Link to post
    Share on other sites

    If the HTML file were expanded in a browser then saved, would it compress smaller than the same file as a PDF?  Or would the HTML source compress better?  Seems a little testing is in order if it hasn't already been done.  I gather the want is to make the transmission as small as possible.

    Share this post


    Link to post
    Share on other sites
  • Original Poster
  • The thing with PDF is, is that the formatting is the same across systems, regardless what OS you run and what fonts you have. With HTML, even across Windows systems links to images tend to break. It's also more printer-friendly, for those who want it on paper.

    Share this post


    Link to post
    Share on other sites

    I might not be an expert in programming or HTML, but how about, a set of different word documents in which we describe the stuff in different parts? So for example we can split the documentation into:

     

    1) Introduction and updates (description)

    2) Installation

    3) Roads

    4) Highways

    5) Rails

    6) RTMT

    7) Notes

     

    Would that be too hard to accomplish? We get 2 benefits from this, the first being that we dont have a massive 130 pages guide to look thorugh, and second, you can go straight to the part you need directly through the document needed for that part. Also, I dont think people need an online documentation when we already know that everybody downloads it. 

     

    Just an idea =)

    Share this post


    Link to post
    Share on other sites

    While I can read Word documents, I don't have MS Office.  I have Libre Office which does a pretty good conversion job.  However, by default, it is correct to say that PDF can be read everywhere.

    Share this post


    Link to post
    Share on other sites

    ...If NAM 33 is to be documented, we may end up having to start over from scratch, which, with our resources, isn't really feasible.

     

    -Tarkus

     

    What about using the SC4 Encyclopaedia at SC4 Devotion

     

    http://www.wiki.sc4devotion.com/index.php?title=Main_Page

     

    or some other location, if its online it not only can be easily referenced by users, but also means that the NAM team members could edit or add to it as required also add in the ability for those users that want a "hard copy" of the manual to download it in some kind of standardized format.

     

    I've just checked the SC4 Encyclopaedia does allow you to create a "Printable Version" just how that would work with a lot of pictures in it ?

    Share this post


    Link to post
    Share on other sites

     

    ...If NAM 33 is to be documented, we may end up having to start over from scratch, which, with our resources, isn't really feasible.

     

    -Tarkus

     

    What about using the SC4 Encyclopaedia at SC4 Devotion

     

    http://www.wiki.sc4devotion.com/index.php?title=Main_Page

     

    or some other location, if its online it not only can be easily referenced by users, but also means that the NAM team members could edit or add to it as required also add in the ability for those users that want a "hard copy" of the manual to download it in some kind of standardized format.

     

    I've just checked the SC4 Encyclopaedia does allow you to create a "Printable Version" just how that would work with a lot of pictures in it ?

     

     

    That idea is something that has come up in our discussions . . . it would make the process of updating things a lot more fluid, even between releases (particularly if it's determined we need to provide more guidance with a certain feature).  We could produce a "local copy" for use in a given release, and then have the link to the Wiki for the most current and up-to-date documentation.  Most of the NAM Team has Wiki editor rights presently.

     

    -Tarkus

    Share this post


    Link to post
    Share on other sites

     

    ....We could produce a "local copy" for use in a given release, and then have the link to the Wiki for the most current and up-to-date documentation.  Most of the NAM Team has Wiki editor rights presently.

     

    -Tarkus

     

     

    I'd recommend if you do use the SC4 Encyclopaedia then make sure its been added to the Wayback archive as a backup

     

    http://archive.org/web/

     

    It only takes a couple of seconds to input an address and then click the "Save Page" button.

     

    The Wayback is the reason I was able to recover as many of the SC3K and SC4 official files plus tutorials as I did from the deleted Maxis sites.

     

    -catty

    Share this post


    Link to post
    Share on other sites

    Thanks for that link, Catty.  I didn't know it existed.

     

    If the NAM team used this facility, only the web link to the appropriate sections need be downloaded with the release.  Surely this would reduce the size of the download by something serious?

     

    Let's not kid ourselves about thinking some people wouldn't have web access.  How would they download the mod without one?

    Share this post


    Link to post
    Share on other sites

    Thanks for that link, Catty.  I didn't know it existed.

     

    If the NAM team used this facility, only the web link to the appropriate sections need be downloaded with the release.  Surely this would reduce the size of the download by something serious?

     

    Let's not kid ourselves about thinking some people wouldn't have web access.  How would they download the mod without one?

     

    NAM documentation is 48 megabytes; the rest of the NAM is over 600.  So not that big of an impact.  Although I don't think the PDFs compress very well, so it might have a bigger impact on the download size.

     

    Perhaps the documentation should be a separate download alongside the installer.  With a link to this thread, so users have the option to store it locally or view it online.

    Share this post


    Link to post
    Share on other sites
  • Original Poster
  • There is still one important pressing question remaining:

     

    Who is going to write all this documentation?

     

    That has been a serious problem for years now...

    Share this post


    Link to post
    Share on other sites

    It would appear that the NAM team is somewhat incomplete without an avid technical writer.  Starting a technical user guide for the NAM from scratch as it exists now would be a monumental task, and I am sorry but I do not have the energy to undertake such a thing.  Perhaps you could advertise for volunteers.  I will probably take a team with a leader.

     

    BTW, do you fellows have a formal specification that you follow for the NAM, or is it like Topsy and 'Jes growed, Mister Rhett'?

    Share this post


    Link to post
    Share on other sites

    Andreas used to handle a lot of the readme stuff, and designed the whole template we used for the old HTML version (which the SFBT, BSC, NHP, and other teams used as well), but he hasn't been around for a few years due to RL.  It's been all developers doing it since--I did a lot of the NAM 29 and NAM 30-era documentation (and contributed a fair bit to the RHW documentation before that), and had started on some NAM 31 documentation in that same format, before MandelSoft and Ganaram took over with the PDFs.  There's also been issues with some functionality being in a transitional state, which complicates matters as well.

     

    The tricky thing is that there's usually quite a bit of new stuff in a given release, and if a non-dev were writing documentation, they'd have to be as on top of the changes and whatnot as if they were a dev.

     

    -Tarkus

    Share this post


    Link to post
    Share on other sites

    Create an account or sign in to comment

    You need to be a member in order to leave a comment

    Create an Account  

    Sign up to join our friendly community. It's easy!  

    Register a New Account

    Sign In  

    Already have an account? Sign in here.

    Sign In Now


    • Recently Browsing   0 members

      No registered users viewing this page.

    ×

    Help Keep Simtropolis Online, Open & Free!

    stexcollection-header.png

    Would you be able to help us catch up after a bit of a shortfall?

    We had a small shortfall last month. Your donation today would help us catch up for this month.

    Make a Donation, Get a Gift!

    We need to continue to raise enough money each month to pay for expenses which includes hardware, bandwidth, software licenses, support licenses and other necessary 3rd party costs.

    By way of a "Thank You" gift, we'd like to send you our STEX Collector's DVD. It's some of the best buildings, lots, maps and mods collected for you over the years. Check out the STEX Collections for more info.

    Each donation helps keep Simtropolis online, open and free!

    Thank you for reading and enjoy the site!

    More About STEX Collections