training materials feedback - Oct. 22 - AC

[mradamcox]

Overall Comments

We have a lot of information in the official Arches documentation regarding many of the topics and content covered here, but these slides make no reference to it. I think an effort to link to existing documentation where possible should be undertaken. CLI command reference, etc.

Generally, I think the course flows well overall, and I really like the in-depth examples and lab contents. However, after working through it, I think that consideration should be given to the following restructure (modules would be renamed of course):

• Module 1: The Arches Platform
• Pre-course A: Deployment Considerations
• Pre-course C: Django
• Module 2: Introduction to Datatypes
• Pre-course B: KnockoutJS
• Module 3: Building a Custom Datatype
• etc. (the rest unchanged)

A couple reasons for this suggestion

• The knockoutjs primer would fresh in peoples' minds right before we begin working with components. Otherwise, it's a little isolated with it's location early on the first day.
• The discussion of deployment considerations and architecture will make more sense after some basics of Arches' about Arches components have been discussed.

I think it would be good to clearly describe the end state of the project at the end of each module. What should be registered? What should be working correctly? etc.

Module-specific Comments

Note that all bold numbers correspond to the urls generated by the service on github pages. These are based on the state of the repo at commit 51ce70a77a215d7fc294af6dede1a3114b27d18b (Oct. 12).

Pre-course A: Deployment Considerations

General Comments

• Add architecural diagrams... For me a basic diagram that Alexei drew was one of the most important takeaways from Shendish in 2014.
• 6 mentions distributed architecture, but this is before the various Arches components have been introduced. So, people may not know what that means. Would it make sense to reorganize that?
• 7 mention linux flavors? windows "Difficult to set up, must use IIS" seems a little confusing. Are you saying that IIS is difficult to set up, or windows is? Also, every OS needs a webserver, so why mention IIS here?
• 9 says that different cloud services have positives and negatives, but doesn't actually present positives and negatives of each...
• 10 Offer back up strategies? (cronjob pg_dump, db replication, RDS snapshots, etc.) Offer examples of how e-mail can be set up? What is the best service to use? I definitely appreciate the Let's Encrypt suggestion.
• 11 Projects/Packages content is duplicated from 10
• It would be nice to actually learn about the Lincoln Arcade (btw, ARCADE?) architecture (how distributed is it? what e-mail server does it use? what SSL cert? what size are the server instances?) and what led to these decisions.

Proofreading

• 4 fix "Is there sufficient in-house resources..."
• 5 In-House not In House
• 5 "upfront" not "up front"
• 5 and 6 "Scalable" is such a hot word nowadays... could be used here
• 7 dependencies not dependancies
• 13 in-house not In House
• 14 bad formatting

Pre-course B: KnockoutJS

General Comments

• Consider putting documentation and tutorial links fully typed as well, e.g.

  Docs found here: https://docs.example.com

  instead of

  Docs found here

  in case this text ends up in a non-hyperlink format (copy/paste, etc.)

• 26 consider changing first line to "Composed of a template (HTML file) and view model (JS files)" or something like that.

Proofreading

• 16 make list capitalization consistent with headers used in later slides

Pre-course C: Django

General Comments

• In the models and views slides, you say "Models (models.py)" and "Views (views.py)". I think it may be nice to have mention that in Arches these are actually many files ("models/resources.py", "views/search.py") etc. I know this is a general django section, but Arches doesn't actually have a "views.py" file, so I think it would be nice to acknowledge this here.
• 39 It may not be actually consistent with Arches, but something like {{datatype.name}} instead of {{datatype.datatype}} may be more clear. Also, in python terms what is "datatype" in this example? (dictionary), so this is a list of dictionaries? It may be helpful to say this explicitly.
• 41 suggest changing the DATABASES example to show postgres credentials. add note here about settings_local.py?
• 43 put in admin page link localhost:8000/admin for mucho clarity

Proofreading

• 32 missing period in first paragraph, also fix "...but it takeS longer..." in second paragraph
• 38 change localhost:8080 to 8000

Module 1: The Arches Platform

General Comments

• 49 this is the content that could be integrated with a diagram, or the relevant "Distributed Architecture" discussion in Pre-course A. Also, I'm not sure the best way to say it but Postgres is your actual database, and Elasticsearch is an index that can be rebuilt anytime from your database (i.e. in reality there is no novel data in elasticsearch, it's just an extra layer (though, of course, necessary)).
• 50 add link to docs repo
• 51 add link to code of conduct (on archesproject.org)
• 54 second line should mention the term "graph", too, right?
• 59 this second comment about template file paths could work really well way back in the intro to knockoutjs section.
• 60 Arches uses requirements_dev.txt, not requirements-dev.txt. You could mention that sphinx, etc. is already in requirements_dev.txt
• 62 Specifically, "you are expected to have Arches installed in a virtual envrionment. You will use this virtual environment for all work in the rest of the class." I think something like that would be very helpful, and would make unnecessary any further mention of "with the virtual environment where you installed arches activated" in the rest of the slide content.

• 63 This slide is super important. I think a recommended installation directory structure would be helpful, something like

  /swindon
      /env
      /arches-dev-training-project

  Also I recommend adding cd arches-dev-training-project to make it clear from which directory these commands must be run.

  Also, you should mention settings_local.py here, as this must be configured before running. Windows users need to set GDAL path, anyone using external pg or es will need to configure that stuff. for what it's worth, I can make an ES instance open to anyone who wants to use it.

  I don't think it's wise to ever have settings_local.py in version control. At any rate, it's an a-typical and not really a good precedent to set. An alternative would be to put a settings_local.py file elsewhere for download, like the one I have provided here: http://ftp.legiongis.com/swindon_materials/settings_local.py.

Proofreading

• 52 and 53 compose not comprise
• 55 consistent "Elasticsearch" capitalization (pretty sure Elasticsearch is what they use). This could be applied to the whole document.
• 60 second line, "your" not "you're", and add apostrophe to "projects"

Module 2: Introduction to Datatypes

General Comments

• 71+ These codes examples should include file paths to where these files would be in a project.

Module 3: Building a Custom Datatype

General Comments

• 77 I think it would be helpful to have people run

  python manage.py packages -o function list

  before and after running the command to register the function.

• 83 Similar to above comment, I think it would be good to take a minute to make sure people have seen that there is nothing in the search page (0 results) and nothing in the Arches designer (no resource models) before having then import these things.

Module 4: Introduction to Components

General Comments

• 91 Arches uses .htm instead of .html (I think the discrepancy between the real files and the slide could be a little distracting to some).
• 92 Config files can go anywhere, but where should they go? I could see this type of flexibility being more confusing than useful. Is there a preferred location for these files? Where are the config files for default components?
• 98 This is generally really helpful information, and perhaps could be mentioned much earlier on? Just a thought.

Proofreading

• 101 Suggest changing "As components widgets consist of front-end code only" to "As widgets are just a type of component, they consist of front-end code only" just for clarity (if that's indeed the intended meaning of the sentence)
• 112 & 115 Use code syntax for file path
• 121 suggest removing $(env), or perhaps adding this to all other command examples. Without $(env) is nice because you can more easily copy and paste, with it is the clear indication that a virtual env is in use. Personally I think without is better.

Module 5: Widget Development

(no notes)

Module 6: Card Component Development

General Comments

• 133+ add path to file

Module 7: Report Template Development

(no notes)

Module 8: Projects and Packages

General Comments

• 155 Mention that images for the front slide show are stored in projects (could just be added to the existing list that mentioned html).
• 156 Why not reference the RTD docs content on settings inheritance here? At any rate, a fully explanation in this slide of how settings.py (all of the permutations of that file) interact with the UI-defined Arches settings.
• 159 Use of the word "components" in the second item may be confusing here.

Module 9: Arches Geospatial

General Comments

• Mention that Arches can also consume WMS, as well as vector tiles.
• Why not reference all of the examples in https://github.com/legiongis/arches4-geo-examples? This repo could be cloned by attendees and the examples loaded directly into their project.
• 180 What, specifically, are the issues with tilestache?

Proofreading

• 165 "archesproject" add space

Module 10: Creating a Package

(no notes)

[robgaston]

@mradamcox Thanks for your comments!

We will work to factor in your proofreading edits.

RE: reorganizing the modules - unfortunately, I doubt that's feasible this time around as students have already been told that day one will be the optional "pre-course" stuff. Also, that would force students who don't need the pre-course material to attend those portions.

FYI, A lot of the content suggestions that you've made here are things that will be discussed in the class, but perhaps not captured in the slides. These are good notes, regardless.

Thanks again for the review!

[mradamcox]

@robgaston That makes sense about the module order, thanks for the extra background.