Developers' Guide

[davidfarmer]

If we want more people to contribute, it will help to have a developers' guide. Maybe a target is when mathbook becomes pretext and dev becomes master.

For now, this issue can be a place to put items we want to remember to put in that guide.

The comments below on javascript for showing/hiding items made me think about the need for a dev guide:

Many resources are loaded onto a page by marking items with an id or class, and then doing something to the contents of the item. In many cases, the item has to be visible: if you create the resource in a hidden div and then show it, it may be broken or not function at all. Examples are sage cells and the GeoGebra calculator. Thus, if you want to hide it and then show it, it is not a simple manner of making a div visible: you have to run that external javascript the first time it is shown. (Another option, which I do not favor, is to make it visible but far away from the visible screen.)

Some resources destroy the original container, so it is safe to repeatedly run that Javascript. Examples are Sage Cells and MathJax. A non-example is a GeoGebra calculator. That is not a design flaw, because their model is to have only one calculator on the page. But it you want to allow repeated showing and hiding, you need to create it only once, the first time you show it. (Actually, I don't know what happens of you try to make it twice, because I implemented it as described in the previous sentence.)

We are still figuring out best practices about what javascript is embedded on the page, and what is in an external file (which at the moment is likely to be the cryptically named javascript_add_on.js).

[rbeezer]

Add various conventions on code style, git commits, etc. that will help newcomers feel comfortable and not require lots of repeated explnations.

Perhaps some XSL tips I've been collecting.

[davidfarmer]

Accessibility restrictions on choice of colors.

Likely pitfalls:
-the color for links in the text has to have a 3:1 contrast ratio with the black main text. -the highlight color has to be light enough that it has sufficient contrast with the link text

[rbeezer]

Acessibility testing, free tools like https://www.deque.com/products/axe/ (in Author's Guide from #658).

[rbeezer]

Deprecation: what, when, and how. Especially command-line switches.

Include discussion of the script for "fixing" deprecations.

[rbeezer]

Developer's Guide now exists.

At 33a90f5a1990d19c4ea953f4fc512b0fcebad24a, 42eb55502dd58709ab21a8f427594900692772e9.

To do:

• Write about pull requests, using projects database as example
• Integrate into website build
• Advertise

Let's keep this open until we clear some of the ideas given here.

@davidfarmer - can you adjust the Road Map to reflect this exists and needs content?

[davidfarmer]

Roadmap adjusted to indicate the Dev Guide exists and needs material.

@davidfarmer - can you adjust the Road Map to reflect this exists and needs content?

[rbeezer]

Could use:

• Style guide for code contributions
• Deprecations - how to

Accessible colors should go in the Author's Guide, so make a new issue when that is the only barrier to closing this.

[davidfarmer]

Reopen if still relevant.