About issues, email and sub-tasks

The idea is that each of the issues in the requirements list is a starting point.

Over time, some of these will be split up in multiple sub-tasks (e.g. 'Dramatically Clean up CSS' will have to be separated into multiple courses of action that all contribute to the end-result).

A few basic rules:

• Avoid email. Any information that can be put into one of these GitHub issues should be typed in there.

If you put any information into an email it will get lost.

It won't be visible to all stakeholders.

Instead, if you put it in a GitHub issue, it becomes part of a searchable database with project-related info.

• Please attach any relevant info and sample files to the correct issue record.

If you have sample files, screenshots,... please attach them to the issue.

Some file formats are not accepted, but simply .ZIP-ping them up will allow you to work around that problem.

When attaching files, please first pare them down as much as possible.

Having too much 'real' content will distract from the actual point being made, and makes development and diagnosis a lot harder.

Instead of attaching a full-blown book, you should try and attach a small, mocked up document instead.

It is very helpful if you can mock up a single-page document with just a single text frame or so, and demonstrate the issue using a tiny document, rather than a 'real' InDesign document.

An alternate approach is to make a copy of a large document, and then remove most of the content from it, until you cannot make it any smaller without losing the issue you're trying to show. Strip styles, colors, frames, pages, spreads, master pages, XML structure... until you cannot strip any further without making the issue stop occurring.

If possible, modify the submitted documents to use 'standard' Adobe fonts, rather than whatever fonts the document you have at hand is using. By switching to standard fonts beforehand, and testing whether the issue still occurs on your end, you can increase the odds that the sample document you submit will cause the same issue to occur on the developer's workstation.

• Split up issues into smaller issues whenever you can.

Often, when creating or adjusting an issue record, you'll have an urge to add multiple 'to do' items.

If you see that an issue has become a 'to do' list with multiple sub-tasks, please split it up.

E.g. if you feel tempted to create an issue in the vein of:

Please fix the problems:
- Text should be right-aligned
- InDesign crashes when running
- When you have time, the output file name should end in '.bla'.

you should really create three different issue records.

Otherwise, it becomes very hard to decide when a problem is fixed.

If we leave the above as a single issue record, it might be that sub-items 1 and 2 are actually fixed, but the minor sub-issue 3 is not, so the whole issue-record remains 'not done'.

By splitting, we would have three issue records, two of which are done, and one remaining not done yet, but low priority, so it's easier to manipulate during progress planning.

• Try to move forward

Each time an issue can be progressed towards being closed please do so.

If an issue is assigned to you, the ball is in your camp. When the ball is in your camp, please progress the issue: add any information you can provide, do any work you can do, or if you are the final recipient and the issue is completed, please close the issue.

Once you've done all you can, assign the issue to the person who needs to take over for the next step.