Organizational question that affects the whole chapter – are you primarily talking about types in this chapter, or about Dialyzer? Because the sections on how Erlang uses types don’t really deal with Dialyzer directly. Unless I’m misunderstanding badly, you can’t use Dialyzer without the type annotations, so you probably need that discussion of types for readers to fully understand. However, you could optionally just stick to talking about Dialyzer.
So there’s two paths you can take here, either of which may require some changes:
If you’re talking about Types and Dialyzer, then you should move the sections “How Erlang Views Types,” “Adding Type Annotations to Functions,” “Adding Type Annotations to Records,” and “Creating Your Own Types” to the front of the chapter, immediately after the introduction, and before the “Dialyzer Internals” section. You should also change the chapter title to something like “Dialyzer and Type Testing.”
If you want to keep the discussion just focused on Dialyzer, you should delete the sections “How Erlang Views Types,” “Adding Type Annotations to Functions,” “Adding Type Annotations to Records,” and “Creating Your Own Types.” You should, however, add a note or a paragraph telling the reader where they can learn more about type specifications in Erlang…possibly with a link, or a reference to another book.
The last sentence of paragraph 2, “What you can do with them is use tools like dialyzer to check that the program is consistent.” doesn’t need to be there. You’re still setting up the case for dialyzer; you shouldn’t introduce it just yet. That happens two paragraphs later.
I’m amused by the “Dialyzer will hurt your feelings” warning, but I don’t know why that is, or why it would be in the section on Dialyzer internals.
About the PLT file – what sorts of things do I want to add to it, and why?
In the “Errors” section, I’d delete the heading “Using Dialyzer with ErlyDTL” – you’re just talking about the second of three errors there; inserting a new heading derails the discussion. Just explain the error the way you’ve got it, and move on to the third.
Where you should add a new subheading is when you switch to talking about pattern matches.
The second example in the pattern matching section, the “more complex” error message (which is really complex) doesn’t have any explanation; I imagine you plan to expand on that.
In the “Adding Type Annotations to Functions” section, the paragraphs on abstract types, literal types, complex types, and predefined types fit better in the “How Erlang Views Types” section. There’s also some repetition there, so moving the paragraphs will help you fix that problem.
The “Using Dialyzer with a CI System” section seems to be incomplete. I’ll wait for completion before commenting on it further.
Editorial comments on the Dialyzer chapter:
Organizational question that affects the whole chapter – are you primarily talking about types in this chapter, or about Dialyzer? Because the sections on how Erlang uses types don’t really deal with Dialyzer directly. Unless I’m misunderstanding badly, you can’t use Dialyzer without the type annotations, so you probably need that discussion of types for readers to fully understand. However, you could optionally just stick to talking about Dialyzer. So there’s two paths you can take here, either of which may require some changes:
The last sentence of paragraph 2, “What you can do with them is use tools like dialyzer to check that the program is consistent.” doesn’t need to be there. You’re still setting up the case for dialyzer; you shouldn’t introduce it just yet. That happens two paragraphs later.
I’m amused by the “Dialyzer will hurt your feelings” warning, but I don’t know why that is, or why it would be in the section on Dialyzer internals.
About the PLT file – what sorts of things do I want to add to it, and why?
In the “Errors” section, I’d delete the heading “Using Dialyzer with ErlyDTL” – you’re just talking about the second of three errors there; inserting a new heading derails the discussion. Just explain the error the way you’ve got it, and move on to the third.
Where you should add a new subheading is when you switch to talking about pattern matches.
The second example in the pattern matching section, the “more complex” error message (which is really complex) doesn’t have any explanation; I imagine you plan to expand on that.
In the “Adding Type Annotations to Functions” section, the paragraphs on abstract types, literal types, complex types, and predefined types fit better in the “How Erlang Views Types” section. There’s also some repetition there, so moving the paragraphs will help you fix that problem.
The “Using Dialyzer with a CI System” section seems to be incomplete. I’ll wait for completion before commenting on it further.