A look behind the scenes (Thank you to Janeice DelVecchio)

[Jeanne Boyarsky]

Janeice is a moderator here and focuses on the Cattle Drive. She is also one of the two tech editors of the book. Like me, Janeice is a fan of automated testing. And she brought it to the book.

She asked Scott and I if we would use a "book tool" if she wrote one. Sure!

Janeice wrote a small Spring boot program with POI/HSSF. It parses the Word docs and checks the chapter against some standards. For example, we are required to use certain styles. Or we want to be consistent about "class path" vs "classpath". The idea was that we could automate detection/prevention of some of the errata in our OCA 8 book. We found the tool valuable very quickly. We've added lots of rules to it.Some were things that were wrong. Some were things Scott and I wanted to stay consistent about.

It was even helpful to have book tools for the things we used to catch manually. Knowing book-tool would catch these things let us focus on content and work faster. Just like unit tests give you safety on your code, book-tools gave us safety for our book. And all the rules are unit tested. It's a perfect app for TDD because we are starting with scenarios.

So a big thank you to Janeice for book-tools!

[Janeice DelVecchio]

You're very welcome. I am really so happy you both liked it so much!
You and Scott did most of the work implementing all the rules you needed. My thing is just an engine to run the rules.

It was way more helpful to you than it ever was to me. I wanted to use it to run rules against the code in the text, but with all the snips and one liners, it was hard to write rules meaningful for the code at that level.
That said, it was really nice to know there were certain things that I didn't have to look for while I was editing.

[Jeanne Boyarsky]

Janeice DelVecchio wrote:You and Scott did most of the work implementing all the rules you needed. My thing is just an engine to run the rules.

And yet, it wouldn't have existed without you! The idea of writing the engine (and actually doing it) was all you!

[Sander Hollaar]

the Word docs

Would LaTeX be an option for writing a book like yours?

[Campbell Ritchie]

Good to see you again, Janeice

[Scott Selikoff]

Sander Hollaar wrote:

the Word docs

Would LaTeX be an option for writing a book like yours?

Yes.....  in fact previous books I worked on used LaTeX and I found type setting to be a heck of a lot easier (closer to a WYSIWYG editor), but alas... no.  Word is used because it has built in support for track changes and revisions.  Imagine 2 authors and 3-4 editors are all working on the same chapter.. lot easier to manage/review/approve changes in Word.

That said, we do shift to PDF after a chapter has been reviewed, but then we have to spend a great deal of time ensuring text is properly laid out.  Jeanne knows this is the part I get most nervous about.  On the plus side, we’ve gotten better about consistency so we have fewer and fewer problems moving to PDF.

[Scott Selikoff]

Janeice DelVecchio wrote:You're very welcome. I am really so happy you both liked it so much!
You and Scott did most of the work implementing all the rules you needed. My thing is just an engine to run the rules.

Did I though?  I remember early on I would implement my rules in the form of “Hey Janeice can you make this change...”.  

Seriously though, the book tool has been invaluable for consistency and also avoiding problems before they happen.  As stated earlier we move from word to pdf and parts (especially code snippets) aren’t formed properly, it can take a lot of time to fix.  Thanks Janeice for being a life saver on these books!

[Sander Hollaar]

Imagine 2 authors and 3-4 editors are all working on the same chapter.. lot easier to manage/review/approve changes in Word.

Not to invalidate the point you make towards Word, but this sounds like something Github/Gitlab could provide as well. But likely not as sophisticated as Word. Thanks for the insight.

[Jeanne Boyarsky]

Scott Selikoff wrote:

Janeice DelVecchio wrote:You're very welcome. I am really so happy you both liked it so much!
You and Scott did most of the work implementing all the rules you needed. My thing is just an engine to run the rules.

Did I though?  I remember early on I would implement my rules in the form of “Hey Janeice can you make this change...”.  

I think you wrote a couple. I also remember the one where you specified the requirements in JUnit and asked me to implement the regex. I liked that one!

re LaTex - the publisher actually does support that as an option now. The problem is that the book already exists in Word. When we worked on the OCP 11 books, they gave us backed out Word files. So switching to LaTex now would be a lot of work.

[Scott Selikoff]

Sander Hollaar wrote:Not to invalidate the point you make towards Word, but this sounds like something Github/Gitlab could provide as well. But likely not as sophisticated as Word. Thanks for the insight.

You could, but I think Word is better for reviewing text documents.  Unlike code, which tends to be rewritten in functions or lines, text documents can have a lot more subtle differences.  Also, it allows us to visualize the edits for all changes, not just the most recent one, along with who modified what (based on color).  So, as much as I'd prefer LaTeX, I think it is useful post-submission in editing the document.

[Martin Vashko]

Did you encounter some difficulties managing the documents in Word? I participate on maintaining a documentation in the form of some largish Word documents, and it's sometimes terribly frustrating, as we keep hitting some obscure Word bugs. But our documents were created many versions of Word ago, and that seems to be part of the issue.

Also, which language/library does the book tool use? Is it a VBA or .NET?  (Or, hopefully, something else? )

How did you put together revisions by multiple authors/editors? Were you merging together documents that were edited offline, or did you all simultaneously edit one version stored in cloud?

Scott Selikoff wrote:You could, but I think Word is better for reviewing text documents.  Unlike code, which tends to be rewritten in functions or lines, text documents can have a lot more subtle differences.  Also, it allows us to visualize the edits for all changes, not just the most recent one, along with who modified what (based on color).  So, as much as I'd prefer LaTeX, I think it is useful post-submission in editing the document.

When I wanted to be able to track changes to a LaTeX document using versioning software, I was putting each sentence on a new line. That's ok with LaTeX, which uses two newlines to end a paragraph, but quite an unnatural way to write which took some time getting used to. It was then possible to track changes using the versioning software on a sentence level as opposed to a paragraph level, which is too coarse. I didn't actually co-author the document with anyone, so I don't know how this would turn out.

There are some LaTeX packages for comparing two versions of a document, making highlights similar to Word revisions, so it might be possible to pull two versions from a version control and compare them (not sure about the author information though). But it's quite a lot of setting up and additional work for something that comes out of the box using Word.

[Janeice DelVecchio]

Martin Vashko wrote:

Also, which language/library does the book tool use? Is it a VBA or .NET?  (Or, hopefully, something else? )

Java with spring boot and poi. Could have been done in any language that has a library for word doc. If it were docx, I would have used straight xml traversal.

[Janeice DelVecchio]

Campbell Ritchie wrote:Good to see you again, Janeice

Always good to see you.

[Jeanne Boyarsky]

We are writing a book about Java. Using another language on the book would be heresy

[Martin Vashko]

Janeice DelVecchio wrote:Java with spring boot and poi. Could have been done in any language that has a library for word doc. If it were docx, I would have used straight xml traversal.

Thanks, that makes sense. I guess I spent too many years cobbling up makeshift tools to manipulate Office files using VBA...

Jeanne Boyarsky wrote:We are writing a book about Java. Using another language on the book would be heresy

Good point!