Object Oriented Book Authoring?

[Mark Levison]

I use MS Word to author nearly everything I write:

- Workbooks (for courses)

- Blog posts

- Actual real books (Work In Progress)

Much of what it does is pretty good (visual editing, comments from editors, track changes, etc). There are just two things that are slowly pushing me away - books should be reusable parts (quasi OO) and when someone else makes a change I should always know who it is at a glance.

The two big challenges - my workshop materials are made up of parts that can be mixed for different situations and clients. As stands now if we make a change to a section like "Definition of 'Done'" or "User Stories" that have been used in multiple places we either have to update them all or just declare most orphans. I'm writing blog posts for a series Scrum By Example (https://agilepainrelief.com/notesfromatooluser/2018/08/scrum-by-example.html) and eventually, this will likely become a book - about the unluckiest ScrumMaster ever.

I had hoped one day to find a magical binding tool - where I just created a shell document, wrote a series of include statements and watched a book appear from these parts. I realize that was probably naive at best. 

I've surveyed of the playing field as best I can tell. I'm hoping that my peers and friends can tell - if I've missed anything; and what they have used themselves.

Detailed needs (beyond the object idea):

• Collaboration is possible - I do the writing but also have an editing team - sometimes we make 2-3 sets of changes in a day
• Can see who made which change - one of my editors has a deeper understanding of Agile than the other, it is easier to accept changes from that one rapidly
• Can write comments that aren't just in the body of the work - especially from editing team
• Features we use from MS Word: footnotes, tables, multi-column text, borders on text, page break, even/odd page breaks, lots of embedded images, headings, footers, links, table of contents, occasionally embed PDFs
  

Tools I've looked at:

MS Word - missing support for objects

Scrivener - Pro Does understand that files are objects. It does understand you can rearrange files into parts. Con UI and Usability from hell. (3.0 might improve that) More importantly its not designed for collaboration. It has an internal versioning system, which is effectively just saving zip files. Others have used it with Github: https://github.com/carsomyr/scrivener_starter - but that isn't by design - in addition they're saved as RTF files so no joy in using GIT for diff tools. At best the built-in collaboration is import and merge.

LaTeX - Pro Files are objects; Documents are just text files and so the full value of version control is brought to bear. Con: compile times can get large as documents become big. You have to play lots of games to find themes

This book: Better Books with LaTeX - Clemens Lode - outlines how to use to LaTeX publish a book. Editing can either be via a multitude of open source tools

Markdown - core Markdown is too simple, so people have created Pandoc https://pandoc.org/MANUAL.html and Bookdown: to https://bookdown.org/yihui/bookdown/ to extend Markdown. Question is this much better than LaTeX.

LaTeX vs Markdown: https://tex.stackexchange.com/questions/418962/markdown-vs-latex-for-thesis#419464

--

What are you using for book authoring, workbooks et al?

Cheers

Mark

[Markus Gaertner]

I use scrivener for a while now. Pretty neat.

Best

Markus

-- 

Dipl.-Inform. Markus Gaertner
Author of ATDD by Example - A Practical Guide to Acceptance Test-Driven Development

http://www.shino.de/blog
http://www.mgaertne.de
http://www.it-agile.de
Twitter: @mgaertne

--

---
You received this message because you are subscribed to the Google Groups "Lonely Coaches Sodality" group.
To unsubscribe from this group and stop receiving emails from it, send an email to lonely-coaches-so...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/lonely-coaches-sodality/CA%2BUdPQ-UfTPE5ob7gs4gtTK%3DxKg8W5SaA9xAqVrx7G6WT2zAUw%40mail.gmail.com.

[Yves Hanoulle]

All my books are written in / on leanpub in markdown.

The text itself, I write in text files that are in a sourcecontrol system. that allows me to let others edit them and I can see the changes

Even stuff for myself has been in a source control system for years

the only exception I make is things in google docs, because the collaboration is easier.

For the manuals of my workshops I like the fact that when I make an update, everyone who was interested in the manual can get a new version

y

Op di 6 aug. 2019 om 21:26 schreef Mark Levison <ma...@agilepainrelief.com>:

--

---
You received this message because you are subscribed to the Google Groups "Lonely Coaches Sodality" group.
To unsubscribe from this group and stop receiving emails from it, send an email to lonely-coaches-so...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/lonely-coaches-sodality/CA%2BUdPQ-UfTPE5ob7gs4gtTK%3DxKg8W5SaA9xAqVrx7G6WT2zAUw%40mail.gmail.com.

--

Yves Hanoulle - 0476 43 38 32

• Events I co-organize
• CoderDojo Ghent: http://gent.coderdojobelgium.be/
• Community events that need your help:

• CoachRetreat in your country >> mail me
• CoderDojo's all around the world looking for coaches. This is the Belgium subscription page https://www.coderdojobelgium.be/nl/vrijwilliger-worden
• www.agileconferenc.es all agile conferences worldwide, maintained by the community
  
• Community Tips for hiring a great team: http://www.hanoulle.be/hiring 
• Who is agile "your country version"  >> mail me
  
  
• books I helped create
• NEW Arduino met Geike paperback: https://www.amazon.de/dp/9082826267
• Arduino met Geike E-boek: https://leanpub.com/ArduinoMetGeike
  
• Tips from the trenches: scrummaster https://leanpub.com/TipsFromTheTrenches-Scrummaster
  
• How to organise a CoachRetreat: https://leanpub.com/CoachRetreat 
• 96 Visualisatie Voorbeelden https://leanpub.com/Visualisatievoorbeelden  
• The ScaledBallGame: www.ScaledBallGame.org
• PairProgramming workshop: http://leanpub.com/pairprogrammingworkshop 
• Leadership Game: https://leanpub.com/TheLeadershipGame 
• All my books: https://leanpub.com/u/YvesHanoulle

[Markus Gaertner]

Oh, and my book, I wrote with emacs in latex. :)

Best

Markus

-- 

Dipl.-Inform. Markus Gaertner
Author of ATDD by Example - A Practical Guide to Acceptance Test-Driven Development

http://www.shino.de/blog
http://www.mgaertne.de
http://www.it-agile.de
Twitter: @mgaertne

On Tue, Aug 6, 2019 at 9:26 PM Mark Levison <ma...@agilepainrelief.com> wrote:

--

[Mark Levison]

@Markus - Scrivener - I've tried and where it me alone it might work. The challenge is that it is team friendly. Emacs and LaTeX. With LaTeX where there any issues? Any pain points?

@Yves - like you I'm leaning towards text files stored in a source control system. What formatting to you use? Markdown, LaTeX, Troff? (We already automate copying of pdf's so attendees get updated workbooks. I just use a powershell script.)

Thanks for all so far

Mark

To view this discussion on the web visit https://groups.google.com/d/msgid/lonely-coaches-sodality/CALO_cXbKe8aNuMvQvXq2Y18qSi4GjHjp0U0fyrMJEsn6g0%3DrYg%40mail.gmail.com.

[Markus Gaertner]

Hi Mark,

I wrote my diploma thesis with latex, so I had many much scaffolding already in place to use. Also you should know the most convenient packages to use, and of course the latex syntax.

Best

Markus

-- 

Dipl.-Inform. Markus Gaertner
Author of ATDD by Example - A Practical Guide to Acceptance Test-Driven Development

http://www.shino.de/blog
http://www.mgaertne.de
http://www.it-agile.de
Twitter: @mgaertne

To view this discussion on the web visit https://groups.google.com/d/msgid/lonely-coaches-sodality/CA%2BUdPQ8bsaHhE0%2ByXasGh3Ed4PwuTd5pXW%2BxAoWHatMgfmQ5CA%40mail.gmail.com.

[Josh Bruce]

Usually I watch way longer before jumping in, but this intrigued me.

I use iA Writer + GitHub + Leanpub. This combo lets me edit + create on any device at any time commit and review when convenient. 

With that said, also finding a shared Pages document to pretty wonderful and I think you can reorder sections easily.

Also, have you looked at the Federated Wiki (not MediaWiki, but the one Ward is still working on)?? What you're describing seems to be pretty much the premise.

Hope that helps.

Cheers,

Josh

ps. Agreed on the Scrivener UI. Years ago I offered to help after another designer did a redux for it and was shot down...I suppose it works for the majority of the target audience because they're still doing it, and people are still buying it despite a fair amount of alternatives.

pps. You're making me think I should dust off the notes for a document manager I had back on the day. :)

[Bonnie Aumann]

Tech writers who used to maintain Windows Help Files used a tool l can't quite remember but might be this one because they had the problem that not only might pages of content change, but smallish pieces of text like what's in a drop down menu could change and would need to be changed everywhere. 

--

Bonnie \\ Aumann about.me/bonniea twitter: @bonniea pronoun.is/they

To view this discussion on the web visit https://groups.google.com/d/msgid/lonely-coaches-sodality/CALO_cXa%3Dnp8gE99LfhwESHLH8TM%2BAoLeTm7hn906cTOcSaQbww%40mail.gmail.com.