I don’t have trouble with the material, I just feel like the layout of the books aren’t as good as could be. (I am generalizing books but I’ve only purchased iOS Apprentice and Core Data by Tutorials. Other books may be different)
My main issue is that instructions can be hidden in a paragraph of text. I believe the solution is simply to take instructions for the user to do and put them into bullet points. So instead of:
Select the NoteToNote mapping. Select the attachments relationship row in the list of relationships so that the Inspector changes to reflect the properties of the relationship mapping. In the Source Fetch field, select Auto Generate Value Expression. Enter $source in the Key Path field and select NoteToNote from the Mapping Name field.
You have:
Do (Or similar prompt)
Select the NoteToNote mapping
Select the attachments relationship row in the list of relationships so that the Inspector changes to reflect the properties of the relationship mapping
In the Source Fetch field, select Auto Generate Value Expression. Enter $source in the Key Path field and select NoteToNote from the Mapping Name field
You could used numbered lists if it makes sense as well.
If an instruction has a code block attached to it it is just indented below the bullet point text.
It’s a small change but it makes it much more readable and much less likely a user will miss a step. At least it would for me.
@aestus Thanks very much for your question/suggestion! I think you make a very fair point. Because the books are intended to be a bit more than just a list of instructions for the user to do, the instructions generally are put in paragraph form so that they can be accompanied by any necessary explanatory notes from the author. I took the liberty of going through the “Core Data by Tutorials” book, and believe it or not, I saw examples of what you suggested already in place (i’ve even attached a screen shot just in case!)
One thing I will say that ultimately, it is up to the author’s discretion as to how they want to convey their instructions, and explanations to the user, and we do have many editors who scrutinize the work thoroughly before it gets published. The unfortunate reality is, it’s very difficult to please everyone, but we do try our best We welcome your feedback, and perhaps we may consider applying this more frequently going forward.
Hopefully our future publications will be more to your liking!
I definitely know that listed actions are included in some places. I also understand what you’re saying. I guess you can count this as my vote for clearly separating explanation/notes and actionable instructions. For example:
Now we are going to do Thing A. We do this because _______.
Do
Step 1
Code
Step 2
Code
Explanation of code if needed.
Next bit of notes.
I get what you mean about not wanting to just be a list of steps. Basically what I’m saying is it’s the same structure but instead of a paragraph of instructions, it is a list in between paragraphs of notes. It may be me but this is a much clearer way to convey information. Well anyway I appreciate the tutorials, just wanted to voice my opinion.
(i’ve even attached a screen shot just in case!)