search

docker-captains / dockerbythecaptains

Docker by the Captains - a book covering all aspects of Docker, written by the world's leading experts
99 stars 33 forks source link

Assignments & chapter size #4

Open vfarcic opened 7 years ago

vfarcic commented 7 years ago

I think that we split the work too much. There are many subchapters (which is fine) and each of us is assigned to one or more of them. The problem is that each of us has a different style of writing and that will produce a very inconsistent book. We already agreed that the book is an effort from many people so some level of inconsistency is unavoidable (and even welcome). However, I would suggest that each of us writes a bigger chunk of the book, instead of a few disparate subchapters. I, for example, put myself into three subchapters and each belongs to a different chapter. Wouldn't it be better if we are assigned to chapters instead? A few captains can work on one chapter. That would make our book look similar to https://www.amazon.com/Site-Reliability-Engineering-Production-Systems/dp/149192912X . Each chapter would be a story in itself (with a common theme) instead each subchapter being a separate narrative. As it is now, it would not be a book but more like a collection of many blog posts.

sixeyed commented 7 years ago

If we're aiming to match the CE release schedule, and get an up-to-date version each month then I think chapters need to be discrete and small. I'd prefer to use the structure to give the context, e.g. a chapter on swarm mode security is standalone, and can be written and edited in a month. That chapter lives in a Docker swarm section, which starts with an intro chapter giving context.

jonasrosland commented 7 years ago

I think if this is going to be an ongoing effort requiring updates to chapters for every CE release, you'll need to make that very clear to anyone signing up to write a chapter since they'll have to continuously update or find someone to update the chapters in the future. Also, getting everything ready for 17.06 is a bit aggressive, I'd rather set the process in place and work towards a 17.08 release. That would give everyone more time to fine tune writing (books are not blogs) and editors will have time to properly edit content so it's coherent. Since it's a volunteer effort and not a paid assignment it cannot take precedence over our day jobs, which also sets a time limit of the amount of work everyone can assign to this. I'm very positive for this book and I'd gladly write a chapter or help editing, I just want to make sure we're setting real deadlines that can be met and not rush things.

vfarcic commented 7 years ago

17.08 is also unrealistic assuming that we'll publish a book properly (editing, review of each chapter, review of the whole book, rewriting, and so on). I think that the end of the year is much more realistic.

This endeavor is a lot of work. Much more than it looks at the beginning. A couple of captains already published a book (or two) and I'd like to hear their opinion.

sixeyed commented 7 years ago

@vfarcic I have a long book in progress, and it's taking way too long - which is one of the drivers for this project. I also wrote a few short eBooks and that was much better. I can easily write a chapter in 2 weeks, but sustaining it is difficult. That's why I think many small chapters with each author picking up 1 or 2 would work.

sixeyed commented 7 years ago

@jonasrosland I don't think there has to be ongoing responsibility - let's say we create an issue to deliver a chapter and one person picks it up and delivers. If there's a big change in that area in the future then there's a new issue to rewrite the chapter. That would be open to anyone, there's doesn't have to be long-term ownership of chapters by the original author.

vfarcic commented 7 years ago

@sixeyed You're right. Writing a chapter is relatively fast. Moving a chapter through a publishing pipeline is slower and takes more time. In our case, I'm not worried about writing chapters. That should not take long. What will take time is going through them over and over again until they make sense as a whole. The result of our writing will be a set of random sub-chapters that are not related with each other. They will look as a collection of random blog posts. What comes afterward will be a long process. Making a book out of our chapters will require a lot of work both for those who wrote it as for those who will review it.