FLOSS Weekly Episode 749 Transcript

Please be advised this transcript is AI-generated and may not be word for word. Time codes refer to the approximate times in the ad-supported version of the show.

0:00:00 - Doc Searls
This is Floss Weekly. I'm Doc Searls. This week, Jonathan Bennett and I are talking with Kyle Rankin, my old colleague from Linux Journal. Kyle knows like everything, but the cool thing is he's not only written like 12 books already. He just wrote a book on how to write a tech book. It's really good and he gets really thorough on what we need to do. If you've ever been tempted to write a book, or even if you should be tempted to write a book, then maybe you should especially for technical you might be qualified Listen to the show or watch it, whichever works for you. That is coming up next. Podcasts you love From people you trust. This is TwiT.

This is Floss Weekly Episode 749, recorded Wednesday, September 13, 2023. That's in Chapter Three. This episode of Floss Weekly is brought to you by Discourse, the online home for your community. Discourse makes it easy to have meaningful conversations and collaborate anytime, anywhere. Visit to get one month free on all self-serve plans, and by our friends at ITProTV, now called ACI Learning, aci's new cyber skills is training that's for everyone, not just the pros. Visit Twit listeners will receive at least 20% off or as much as 65% off an ITPro enterprise solution plan. After completing their form, you'll receive a proper quote based on the size of your team. Hello again, everyone everywhere. This is Floss Weekly. I am Doc Searles and this week I am joined by Jonathan Bennett himself.

0:02:00 - Jonathan Bennett
Hey Doc, it is great to be here.

0:02:04 - Doc Searls
Great to be here too. Whoever this is, it's like the great here, the great here. That is where you are in your head, listener or viewer, in your eyeballs. Somebody told me recently that the eyeballs are the part of the brain you can see, and I haven't been able to get that out of my mind ever since, that's not wrong.

It's not wrong. Your ear drums are kind of hidden way in there so you're not looking at those. Your brain is looking at me. Stop it Anyway. So our guest this week is Kyle Rankin. You familiar with Kyle? I am very, but you probably may not be.

0:02:49 - Jonathan Bennett
I am not. I've never talked to him before except the quick pre-show we've had. Seems like a nifty guy. I'm looking forward to hearing what he has to talk about Writing tech books. I think he wrote a tech book about writing tech books, which is sort of in that.

0:03:02 - Doc Searls
That's right, it's kind of a fourth wall, you sort of sort of think, yeah, and I just know Kyle.

I mean, we were colleagues at Linux Journal for many years and I just knew Kyle as kind of this is a do-and-reference, a sort of our mentat on the staff. He knew so much and could solve so many things and was a jack of so many trades as well as a good writer, that I think any single description doesn't do him fair. So I'm going to read off what he sent me, but probably not the entire paragraph. It's a lot Technologist author, false advocate, speaker, two decades of professional Linux experience, a dozen books on security and open source software, including how to write a tech book, and Linux hardening in hostile networks. It sounds like Combat Ready or something. Award-winning columnist and tech editor for Linux Journal and I've spoken at many things. I think it was at Fosdown. He gave a great talk. Was that a Fosdown? I'll just bring him in. Hey, Kyle, Welcome to the show.

0:04:14 - Nathan Freitas
Hey, thanks for having me on.

0:04:16 - Doc Searls
What was that we were at in Bristol in the UK? Oh that was Free.

0:04:21 - Nathan Freitas
Node Live.

0:04:23 - Doc Searls
Free Node Live. Okay, free Node, live. Yeah, free Node is an IRC, and we have one of those going in the background here too. So welcome to the show. Welcome to the show. So what is the latest book? Give me the premise about that.

0:04:39 - Nathan Freitas
Yeah, sure, yeah. So the latest book is called how to Write a Tech Book, so it's a tech book about how to write a tech book. The entire thing is very meta, from the beginning to the end.

0:04:51 - Doc Searls
It's not to be confused with the company. Right, exactly, not to be confused. It has no relation to the company.

0:04:57 - Nathan Freitas
And it's not yet. It's not virtual reality. So it started when I was actually working on a separate book that I published earlier this year. It's been a busy year as far as my writing goes, and I wanted to collect all of my old Linux journal articles that I still found relevant, and so I took all of the, because I refer to them all the time still, you know, even to this day, even though some of the articles may be up to 10 years old. Sometimes when you're wondering how do I do XYZ and not, you remember? Oh wait, I wrote about that in Linux journal, you know, back in 2003 or whatever. You know. So you go find that article. Well, I know where they are because I wrote them, but I don't think a lot of other people you know can instantly remember where this article is.

So I decided to compile all of that into a book that I ended up calling like the best of hack and slash, and in the process of doing that, I wanted to. It's not, it wasn't an ideal book for a traditional publisher to take on, because we're republishing old articles, that sort of thing. So I thought, you know, I'm going to try out the self publishing thing for the first time and climb this learning curve along the process, including at one point, you know, needing to create a print ready proof of the book. And so I gave myself a weekend crash course in La Tech to format this. And so I was at. I was at this crossroads at the time where I could either learn something like Adobe InDesign or Scribus or, you know, maybe Scribus, but basically a GUI program to do print ready formatting or I could learn La Tech, which let me do it in them. And so to me it was a clear. It was a clear and obvious choice. So I ended up going with La Tech, spent the weekend, gave myself a crash course, found an excellent book template and then was able really quickly actually to format and lay out a professional looking book that that met my standards, having worked with a lot of traditional publishers over the years.

After I did that, I was telling some friends and colleagues about it. I think three times a one day I got the same question well, are you going to write up how you did that? Because they were all sort of interested. Well, how do you do that? And I, after the third person, I realized, you know, I think there's a book there. And so I ended I realized, well, it's not. It shouldn't just be like a self publishing book or just a book on how to format something in La Tech.

But instead what I did was I sort of compiled everything I know about writing technical books, you know, going back many years, going back, you know, like 1012 books ago into a volume that guides people through the process, because I realized there's a lot of people that could write a book, could write a technical book in particular. But it's almost like I mean, for example, I only got into the industry because I knew somebody, essentially, that guided me along the process and invited me in to this world. But there's a lot of people that don't have that and it shouldn't necessarily be that way. So I wanted to write a guide for someone who has a textbook in them to write but doesn't know where to start, and it just sort of walks you through everything from the idea all the way through. You know reprints and second and third editions.

0:08:05 - Jonathan Bennett
So I'm curious about a lot of things about this, actually. But what service do you use to publish then, if you're, if you're, self published? Is that, is that Amazon, I'm, I'm, I think Amazon offers this. Is that what you went with, amazon?

0:08:21 - Nathan Freitas
does offer. There's a number of services out there that you can choose. Amazon's one of them. There is Lulu, there is Ingram Spark I want to say it's in the book, but I think that's the name as well. There's a couple of different.

There's a lot of self publishing options out there that are strictly ebook only, but I wanted to have the option. There's a couple of criteria for me personally. I wanted to have ebook as an option, but I wanted to have, more importantly for me, I wanted physical, tangible books that customers could buy as an option, and so I looked at all of the providers out there and, at least for me personally, I went with Lulu because it did a couple of things that I wanted, which was one one they provided the e-commerce site for me so that I didn't have to set one up, even though I know how to set it up. I didn't want the the hassle of building my own e-commerce platform for this book, so they provided that they provide all of the print on demand, linking you into all of the print on demand suppliers that they have to print all kinds of different types of books. So in my case, I went with a standard sort of softcover tech book format that you might see like a A5 paper size and then also a what I called the premium hardcover. So it sort of went all out with, turned all the dials up on the premium hardcover.

For people who really like the feel and smell of a book, you know, and care about things like paperweight and stuff, I figured well, there's some of those like myself out there and they'll they're willing to pay a little bit more for a book that has all of that.

So I turned all the Lulu knobs up for that book but then had the sort of default settings for the paperback and then also had a had a e-book. So yeah, I went with them. The other criteria I had was I wanted the ability to be on sites like Amazon and Barnes Noble, and Lulu offers that as well. So I liked the idea of being independent from just being Amazon only, but I also wanted to have a presence on Amazon. So Lulu seemed to tick all the boxes for me as far as that goes, because I they have what they call global distribution, where when you set up a book project you can say I want this to be distributed not just on Lulu's own site where people can go buy it, but I also want it shared for sale on Barnes, noble, amazon and all these other partners that they have partnerships with.

0:10:42 - Jonathan Bennett
If you don't mind my asking. You don't have to answer this if you don't want to, but what does the initial investment look like on that to get published through Lulu and what's your progress on trying to make that back?

0:10:54 - Nathan Freitas
The initial investment's mostly time, so it's not. That's one of the other benefits of it is that it's not that expensive. So my very first book that I published. So I published two books on Lulu now this year. The first one was that best of hack and slash book that I talked about, where I combined all those articles. That one the articles were already written, so I didn't even have the time outlay of having to write them. Right, they had already been written and edited. I just had to compile them and then format them. So I actually went from conception to a published book in less than a month. Am I doing this? Because the articles were already. You know how do you publish a book in under a month? Well, you have it already written. That helps a lot. And because it was already edited, I didn't really need to worry about the editing. I just needed to spend personal time learning how to do print proof formatting.

Now, when you're writing a textbook, you already have to concern yourself a lot with formatting. It's I liken it somewhere in between writing a how to book and writing an academic paper, where academic papers the formatting is everything and there's very strict rules on how to do formatting and how to do you know footnotes and all of that stuff. Tech books sort of sit in the middle where if you're reading a textbook, you may not realize you're doing this because it sort of it talks to your brain directly. You may not notice all of this minute formatting that goes into a code block, for instance, where certain things are bold, certain things are italics, certain things aren't, and you know and why is that? And all of it's to sort of subtly guide your brain into knowing what is a command I'm supposed to type in a terminal, for instance, which variables are truly variable, which should be typed in verbatim, all that stuff. So I'd already done all of that, because that's just part of writing a textbook for a traditional publisher.

But it was the extra parts that took time from learning how to take all of that and then have a print ready, proof that is ready to send to a publisher to print in PDF form. So that took a couple of weeks. But yeah, so as far as the cost, it was the cost of getting a couple of print samples sent to me. So we're talking, I don't know, like maybe 20 bucks. I would say something like that Wow, yeah, because you know, because you're not. You know, obviously you're selling the book for more than it costs you to print and when you buy a print proof from Lulu for yourself, they only charge you the print cost. So in part of the requirement for shipping, for going distributing through Amazon and the others, is to, once you have it uploaded, you need to print and you need to get them to publish an actual copy and send it to you for review to catch mistakes, and then once you approve that, then it. Then it gets sent out for Amazon and everyone else, which is good, because I found mistakes, of course.

0:13:41 - Jonathan Bennett
Yeah, yeah, yeah, happens all the time. And Lulu prints on demand, it's print on demand yeah. Yeah, awesome.

0:13:48 - Nathan Freitas
There's. There's certainly pros and cons with that. In different print on demand. I mean it's a lot better these days than what I hear it used to be. As far as quality and consistency goes, they've been pretty good about it. I mean, that said it's, whenever you're printing a one off, compared to say, printing off 10 of something or 20 of something, it's a lot easier for inconsistencies to show up. Usually it's nothing like. I've only run into a couple of mistakes that I thought were big deals where and. But they're really good about that sort of thing. If somehow there's a print error and it crosses a threshold, they they're for both the customer and you as the author. They will ship a replacement. But for the for the most part it's been. For the most part it's been. It's been good quality, especially the premium hardcover. I was really pleased with with how that came up because it's on heavier weight paper and you know, in the hardcover itself feels really nice and tangible.

0:14:43 - Doc Searls
So I have some some further questions on on on Lulu and using Lulu and actually the history of Lulu. But first I have to let everybody know that this episode of Floss Weekly is brought to you by Discourse, the online home for your community. For over a decade, discourse has made it their mission to make the Internet a better place for online communities. By harnessing the power of discussion, real time chat and AI, discourse makes it easy to have meaningful conversations and collaborate with your community anytime and anywhere. Would you like to create a community? Visit Discourseorg. Slash Twitter to get one month free on all self serve plans Trusted by some of the largest companies in the world.

Discourse is open source and powers more than 20,000 online communities. Whether you're just starting out or want to take your community to the next level, there's a plan for you A basic plan for a private, invite only community. A standard plan if you want unlimited members and a public presence. A business plan for active customer support communities. Jonathan Bilava, developer advocacy lead at Twitch, says Discourse is the most amazing thing we have ever used. We have never experienced software so reliable ever. One of the biggest advantages to creating your own community with Discourse is that you own your data. You will always have access to all your conversation history and Discourse will never sell your data to advertisers. Discourse makes everything you need in one place, so make Discourse the online home for your community. Visit Discourseorg slash Twitter to get one month free on all self serve plans. That's

So, kyle, I just want to close an interesting loop here, which is that the very first editor for Linux Journal was Bob Young. He left after a month or two and went off to start Red Hat, and then, when he left Red Hat, he went off to start Lulu. So here we are. So I want to ask something about the writing discipline. I mean, you've done a whole lot of books at this point. How do you get down to? I mean, I imagine knowing that you can get this to publication faster without a lot of the hassle one normally does must help the process of anticipating what's going on. But I'm wondering how you I mean you must have some method that you use to kind of make it all happen.

0:17:34 - Nathan Freitas
I do, yeah, and in fact even in the book there's an entire chapter just dedicated to the writing process and talking about some of the different approaches that both I've taken and that I know other people take to write, because everyone's a little bit different. I mean, even I found find myself changing my habits a little bit over time. But, like, the very first thing is just figuring out the time you're going to write. That's probably the most important part of it to start off with, because for the most part, especially if you're writing a textbook, most people who are writing a textbook already have some sort of day job in technology, which is what's feeding them all of this information they're going to write about. And so, if you already have a full-time job, finding that extra time to write, in particular having focused time that is more than just a half an hour or an hour block, which is important can be tricky. And so first you have to figure out, well, when do I have time to write and what times of day are best suited for me to write. And of course, this has changed for me personally back when I was just with my wife before we had a child. You know, once we had a child and that sort of thing has changed. My wife's also a writer and so if both of us were working on books at the time, then we could, it wouldn't be a big deal for, for example, a weekend. We both say, well, we're both going to go back in their offices this weekend and both work really hard on our books. But when you have a child, that obviously is not going to work very well. So, yeah, so as a result, that changes the calculus right. So that's more of a case of okay, well, I'm going to take this block of time on Saturday, but then not this block of time, that sort of thing. So that sort of first is just making the time to write.

And then for me, the biggest help that I found is writing a very good outline. Over time I've discovered how much I rely on a good outline. I mean to the point I have a whole chapter just on writing the outline, because it's that important. So what a good outline does. And before I write the book I sit down and plot out every chapter, every as best I can think of, every primary header, like every primary section within a chapter, and then sometimes go down into a subsection level, even if I feel that is necessary. And in addition to that, the outline also has a like a paragraph summary of here's what the chapter's about. Here's an introduction to the chapter explaining it. So this isn't just useful for me, this also feeds directly into the book pitch that you will inevitably send to publishers to try to get them to take your book.

But when I sit down to write a chapter, what I do, the very first thing I do, is I go, I've opened a file for the chapter, then I open up my outline and I copy that entire section from the outline about that chapter into the chapter. And I these days, because I do it this way, I actually mark up my outline, not, as in you know, a numbered list, but I mark it and mark down according to headers and sub headers and things like that, because that's how I write my, that's how I do a very light formatting of my drafts before I go into the heavier, heavier duty formatting. And what that allows me to do is I copy in the structure from the outline and then I have a frame, I have a skeleton that I now just have to add flesh to, and so I start with the very first paragraph. I reread the first paragraph, which reminds me what this chapter's about, and you might think, well, why would you need to do that? You know what the chapter's about. Well, that might be true when you first wrote the outline, but a month or two later, after you've written other chapters, and now you're on chapter five, and it helps to be reminded what was my full intention for this chapter, like, what was I trying to say? What was the point? What all of that? And you get that in your mind. And the other benefit of doing it this way is that first paragraph that summarizes every chapter.

In every chapter in a textbook needs to begin with an introduction that tells the reader here's what this chapter's about, here's what we're going to cover in this chapter. And that paragraph is the seed that then becomes the full introduction to the chapter. So you start with that, you flesh out the introduction, perhaps, and then I just go header by header and okay, header one says I'm going to talk about this, let's write that section. Then now I finished that. Now I'm on the header two and it says now I'm going to be writing about this. Then I start working on that.

But what happens is you'll start working on that and you'll find yourself slowing down and procrastinating a little bit at some point, or having some difficulty thinking about how to approach the next part. And whenever that happens to me, what I realize is I've taken on too much at once, I've tried to bite off too much of the elephant, as it were, and what you need to do is that it's. It's, it tells me I need to now split up whatever I'm working on right now into subsections. So whenever it seems overwhelming or I find myself, you know, procrastinating, then it means okay, well, I'm focusing on a first top level header and topic. I need to split this topic into sub topics now and I just split it into smaller and smaller chunks until it's manageable again, and then it flows. At that point it's amazing how fast it flows when you do it that way. And again, if you find it not flowing quickly, it's because it's too big, you're thinking of something too big to focus on, and before you know it, if you do it that way, you finish a subsection. Oh, I'm finished the subsection for this main section, now I'm on to the next one, and then you break that through and before you know it, you're at the end of the chapter and okay, well, now I need to move on.

Now for some, for some books, for most textbooks, there's also lab work involved that you have to factor in this. The book about writing a book had very minimal lab work involved. But what I mean by lab work is if you're writing about, say, writing software, or you're writing about a Linux, how to set up a Linux server or whatever, you have to set up some sort of lab where you're testing all of your steps out and making from a very vanilla environment just to make sure that what you're saying is accurate, and that takes time to that you have to factor in and that can certainly slow you down. And you have to figure out ways to balance writing about something with going through the steps of doing it so that it neither one slows down the other too much.

0:23:43 - Doc Searls
Wow. So talking about outlines, we're all taught in school to hate outlines. I think that's one of the things I don't know if they did there's, certainly when I was growing up. So we have to write with an outline or organize your work into an outline, and most kids are just bored to death by it. But back in the late 80s and early 90s, on the Mac anyway, there was this app called More, which is an outlining app that was also a word processor. It was fabulous. I used it all the time and I could move headers in and out, lined up and down. I could move them in and out and then add text under all of them. I haven't used markdown that much and it seems to be marked as mostly a formatting thing, similar to HTML in a way, but sort of optimized for GitHub or for Git in general, I guess I don't know. But I'm wondering if there's some in writing. Is there some, especially in the open source world, something closer to whizzy wig that one can use outlining with? I?

0:24:55 - Nathan Freitas
Mean I don't typically do a lot of whizzy wig Types. I mean I'm I write. All of my writing has been done in a text editor, in particular in Right, yeah right. But the reason I pick markdown in in particular is I found the process of the other way that you to do it and I've mentioned this in the book is to Is to get a word processor and use a publisher's template. Publishers all have templates that they use for formatting all of their all of the writing.

You could very, very well use a word processor, but the the reason I like using raw text and markdown in particular is that it's very it's very fast and lightweight and visually it makes sense. As far as when you're reading text, for example in a, in italics and markdown is, you put an Astroscon either side of the text, just like if you're chatting with somebody. That's very convenient, because Formatting really when you get into deep formatting of textbooks, it bogs you down and slows you down. It takes it takes a separate part of your brain and a separate type of focus and if you're trying to write the book itself, if you get too caught up in the formatting, you'll go into a rabbit hole where you're tweaking and tuning and getting it to look just right, and it it takes away. It takes your focus away from the text.

I found that by using something like markdown, all I really want to do when I'm using markdown in text there's very little markdown in my first drafts it's simply to remind myself of my intentions. So I intended I I'm writing a word oh, I want that to be italic in the final version. I let me put that there. Or I want this to be a second level header. I need to do something to make sure that. I note that I used to use HTML to do this, but I found out writing all that extra tag, all those extra tags in between, was cumbersome. So with markdown it's you know you can replace a bunch of tag typing a bunch of tags with a couple of characters, so it's just faster.

But yeah, I found that to be very effective because I don't need to have perfect formatting In my first drafts, because I'm not to that stage it. I just need to remind myself future me of what I intended to do, because I've run into this before where I haven't done that and I look at a header I'm like is that, was that a first level header, a second level header, a third level header. Then I have to reread you know, we're talking a month or two later, when I go back to format a draft that I've written and then I have to basically reread that whole section and put it back into my brain and think about okay, well, was that part of this other section, or where, where does it belong? You know, if I don't do it that way, so I think it fits well with this.

0:27:27 - Jonathan Bennett
We mentioned earlier a lot tech, and I bet a lot of people don't know what that is or even how it's spelled. Can you give us the the quick answer to what lot tech is and why you need it?

0:27:38 - Nathan Freitas
Sure, yeah.

So lot tech is a text formatting language. It's based off of tech tex, which was created by Donald Knuth To format text, and it was expanded into lot tech, la tex, which a lot of people say latex, which is fine, like with everything else, an open source in FOS, that there's like five different pronunciations. You can get in great holy wars about which one's right, so, but if you want to be fancy, you can say la tech, which is my understanding is how it's officially pronounced, but in any case it's spelled la tex. However, it is formatted uppercase L, lowercase a, uppercase T, lowercase e, uppercase X and In lot tech, because it's a text formatting language, to make it fancy, they even have a tack for this that that makes superscript and subscript forms of some of these letters in the word I, just to show off that it's a text formatting language. Anyway, why you need to do this is you need some way to, for example, make things italic. Or you need some ways to make the headers of a chapter bigger, a first level header bigger than the second level header. That's sort of thing. While you could certainly cop, you know, select text and increase the font or decrease the font, or bold or not bold, that's cumbersome, and so what la tech allows you to do is just like HTML does for a website Is. It allows you to say this is a header, this is a chapter, this is the, this is a paragraph, and this paragraph shouldn't be indented, or just with very fairly minimal markup, and it allows you to say what this text is, this is a code block, and by saying what it is in a separate file and there's all these great templates out there for this it makes it very fast to say for la tech to then go through and Compile your document and and take all of your hints about what something is and apply all of the formatting that's necessary To that, knowing that it's a header or knowing it's a code block or whatever. It also does great things like automatically adds page numbers to everything in the right place, that automatically reads all the headers and generates Table of contents for you. You can even tag certain Elements and say that I want this to be in the index. This particular section should be in the index under this name, and it will automatically compile and build indices for you in the back of your book. All this stuff. It dramatically Increases the speed at which you can format text if you're, once you climb the learning curve, like anything like this.

But yeah, it's, it's incredibly powerful, it's. It's used a lot in academia. It's used less outside of that, but it's used. It's used by a lot of people. I mean, I formatted my resume in law tech after I climbed a learning curve. I found this really great template for resumes that that I I format, and it's very because it's all based in text if you can type relatively quickly. It's. It's just incredibly powerful and very fast compared to having to get your hands off of home row and go grab a mouse and select text.

0:30:42 - Jonathan Bennett
You spoke earlier about doing some of your formatting in in markup. Is there a tool to convert markup to law tech?

0:30:49 - Nathan Freitas
I'm sure there is, but in practice I tend to not. I haven't done that. So it's possible that it's because there's. There's just more once you get to the formatting phase. The, the markdown that I use is so lightweight and it's just, and it's fairly minimal, it's just like this is a header, etc. That I found it's it's because I need to.

In the formatting part of the process, I'm also doing another round of editing, sort of, because I have to read every word that I've written so I can see how I need to format, if there's something I need to format or add an index for or whatever. And so I'm I'm already kind of reading through the text at anyway. So, changing to hash signs into a a lot text slash section or, you know, subsection, using that formatting is not a huge deal at that point. So, yeah, there are tools. I mean there's tools that convert back and forth between law tech and all the other markup in languages you can think of. I Just personally don't tend to use it. I go through, sort of when I'm in that frame of mind and do it manually.

0:31:53 - Jonathan Bennett
Sure and I've got to ask you when you do you do versioning on your books as you're writing them? And really the question here is do you use get in writing your books?

0:32:04 - Nathan Freitas
I didn't used to, but more recently, my projects because I could. Essentially, I have I haven't yet found, I haven't had the trouble case that you would think you would really need this for, which is I Deleted something or made a mistake or I need to go back to a previous revision for the most part, any mistakes or problems or something that you just sort of roll ahead with you don't. I haven't, I haven't yet Needed to roll back on something how's that? But I like the, the safety net, I suppose, of having that, and so I've started, I've started trying to do that. So, for example, how to write a textbook. It has its own little get repository locally on my machine and it's all in.

Every time I would complete a chapter, I would, you know, commit a new commit with that chapter in it. So I had these milestones. I'm sure it's perfectly possible that in the future in particular, I could see this. If you, if you're, if you were someone who made Massive edits to cut material at some part some point later in the process and then found that you needed some of that material back, this could be incredibly useful to do it that way.

This is a.

0:33:16 - Doc Searls
This is great. We go for you guys. We've got get, we've got lot tech, we've got markup all working together here. I have more questions on this, but first I have to let everybody know that this episode of Floss Weekly is brought to you by our friends at ITProTV. Now calle ACI learning.

In today's IT talent shortage, whether you operate as your own Department or are part of a larger team, your skills must be up to date. 94% of CIOs and CISOs agree that attracting and retaining talent is increasingly critical to their roles. Access more than 7200 hours of content available. Aci learning consistently adds new content to keep you at the top of your game. Your team will thank you for entertaining training. Aci learnings completion rate is 50% higher than their competitors.

Aci learning is excited to introduce cyber skills a solution to future proof your entire organization, not just the IT department. This new cyber security training tool is for all members of your organization. It's cyber security awareness training for non IT. Professionals with cyber skills get flexible on-demand Training covering everything from password security and phishing scams to malware prevention and network safety. Your employees will stay motivated and engaged throughout their learning process with easy to follow material. With a simple one-hour course overview. Your employees gain attack specific training and Knowledge check assessments based on common cyber threats they will encounter on a daily basis. They'll also gain access to bonus courses documentary style episodes, so your employees can learn about cyber attacks and breaches in their own style.

Aci learning helps you invest in your team and and trust them to thrive, while increasing the entire security of your business. Boost your enterprise cyber security confidence today with ACI learning. Be bold, train smart. Visit Twit listeners will receive at least 20% off or as much as 65% off an ITPro Enterprise solution plan. The discount is based on the size of your team and when you fill out their form, you will receive a proper quote tailored to your needs. Okay, so, kyle, you've written what? 10 books now, including this book on how to write books.

0:35:59 - Nathan Freitas
It's an even dozen now, so 10 of them, it's 12 of them.

0:36:03 - Doc Searls
Are you going to lose count at some point?

0:36:07 - Nathan Freitas
I only know because I keep like a personal bibliography on my side. But yeah, it's probably important to note that. You know we've talked a lot about self-publishing projects like this, like LaTeX, but a lot of that only comes in when you're self-publishing and the majority of the book is really about working with traditional publishers. Because I'm aiming this towards someone who wants to write their very first textbook and I recommend against a first-time book writer trying to do all of it themselves and go fully the self-publishing route. I strongly recommend, if you're writing your first textbook, that you do work with the traditional publishers. A lot of reasons for that.

I go into that in detail. I have many other paragraphs explaining why I feel this way, but in summary, it comes down to it's already challenging enough to write your first book. There's a big learning curve you need to climb and editors in the publisher can help guide you through that process, and a good editor is just invaluable when you're working on your first book. Again, it's a big project and so if you're taking on your first project and then, on top of all of that, you also have learned the whole publishing industry, self-publishing side of it, it can be a lot. I'm not saying that no one should do that for their first book. I'd be just recommending against it. I really think it's beneficial to see how it's done with the traditional publisher before you decide to go it alone.

0:37:28 - Doc Searls
So, having written, co-written one book, contributed to a number of books and written another book entirely by myself, which took a couple years, every one of them wanted the document given to them in word. How do you deal with that if you're an open source person? You? Just kind of convert it to. I'm just curious. Go ahead.

0:37:54 - Nathan Freitas
Yeah, and that's common. That's a common like we're mentioning formatting in LaTeX. But the reality with the traditional publisher is, while some publishers will accept LaTeX, for the most part they all have very standard Word doc templates and so when you are ready to do the formatting stage, which is to do all that extra markup we've been talking about, you use their template, because they all have. The goal for them is for you to markup the text and word according to what it is this is a code block, this is a note, this is a figure, et cetera. This is a figure, and then that gets converted to something that the actual page layout person can take and put into something like Adobe InDesign or something else and create a print ready proof out of. But this is sort of the intermediary form. So what happens is you will get a Word doc, but most all the publishers I've worked with have also offered some form of LibreOffice alternative, because they know they're in tech and a lot of their writers work from Linux and don't have a copy of Word, and so all of the ones I've worked with over the years have offered some alternative to the Word template, like a LibreOffice version that does similar things and it seems to work fine.

My process has still always been to separate formatting from writing. I feel that's very important. I feel strongly that's important because it's a separate part of your brain and formatting really does take you out of the writing. So I always write my first drafts in text with, like I said, limited markdown, language formatting. And then the second phase. If I'm using what the traditional publisher is, I paste that into a Word document and then go through the process of using a mouse, selecting text and then picking whatever. They all have style guides that are separate and unique, so you follow their style guide and their examples to mark each of those sections of the text accordingly to using their template, which is like this it's like a program onto itself on top of Word or on top of LibreOffice.

0:40:03 - Doc Searls
I want to say before I know Jonathan has some questions queued up, but I have a. It's not so much a word hack, it was more like a command given to me, but it was really worthwhile which is that if you are, if there's a stage of this that is going to be Word, and if you're going to be writing in Word, starting with the outline view there which, by the way, is one of the worst ever invented. It's absolutely horrible in the extreme, very hard to figure out. But if you get the outline thing right in the first place, that will generate your table of contents and that's really important because that helps you nav around the document. Also, you could have a navigation bar on the left. That is the outline of the thing you're writing and so you know where you are in it. You can actually move parts around in that. So a minor word hack I'm not recommending using Word, but if you're forced to be there, that's some harder and harder and wisdom. So with that, jonathan, you take over Sure.

0:41:07 - Jonathan Bennett
So I'm intrigued that your recommendation is to go with the traditional publisher first, and the reason that that's interesting to me is I've always had this impression that it's very difficult to break into that world as somebody that's unknown or maybe known from writing source code. What's the process? To make the jump to you know who do you email and say, hey, I'd like to write a tech book. How do you, how do you get that first shoe in the door?

0:41:35 - Nathan Freitas
Oh, absolutely yeah, and that's that's chapter three, basically. I go through in detail, but in to summarize chapter three, you start with a really solid book pitch and so the that is explaining the book to a publisher in the language that they expect, and every, all the major tech publishers will give you guidelines on how to pitch them, and in the book I link to all of the major ones that I could find guidelines for with hyperlink so you can go and see what their, what format they want things in. But in essence, what they want is a couple of paragraph introduction to the book. They want an explanation about why the book should exist and what you're trying to do with the book and explain them the market for it, for instance, and what's unique about your book. So if there's existing books on the market, why yours should exist, why yours is going to be different, and then follow the outline. So the outline will then show that you know what you're talking about. You have thought thoroughly about the organization of the book and you have a cohesive book here and you have a book link thing. That's the other benefit of writing a good outline even before the pitch is that it confirms to you that you have a full size book, if you can. If you only have an outline that has three chapters in it, maybe you don't have a full book in this topic or you have to expand the topic. So you start off by taking your outline and turning it into a book pitch. There's a couple of things that you add to a really good outline At the beginning and end, like market, like a little bit of market analysis, an explanation of who you are. It's sort of like applying for two jobs You're applying for the job of author and you're also applying for the job of tech expert because you have to advance them both. That you don't have to like.

Another question is how much expertise do I need to write a book? You don't have to be the foremost authority on a topic to write a book. I've never been the foremost authority on a topic that I've written a book about. When I've approached a publisher, I've been very competent and very experienced in the topic and what's more important is that you have enough experience in the topic that you can explain it well to a listener. That's way more important than being the foremost authority on a topic, because there's plenty of foremost authorities who would be who do a poor job of explaining how to do whatever they can do. So you identify, you create that book pitch and then you identify, you choose which publishers and there's a lot of different fact criteria that go into which publisher you may want to use. But once you choose one or two publishers to approach, then you follow their process and I include links for how to approach them. And publishers are always looking for new authors. That's the other thing. While it seems like there's some secret handshake really just has to do with the fact that they can. You know, if they're going to a conference or editors going to a conference trying to find an author for a topic they're going to. Just they're going to start by approaching the people that have a name in that topic just because they're trying to find someone with authority on it to write about it. But they're always looking for, you know, new authors that they can, they can bring in to write about topics. I mean my.

I got my first book simply because O'Reilly was looking to write a book about nopics, which was this great live CD back in the day, and I happened through and I go through the story in chapter one, but there's through a sequence of events.

I became known by someone who happened to work at O'Reilly for having expertise in nopics and he just came to me one day and said hey, would you like to write a book about nopics? And I said I don't know, sure, sure, why not? And he said, okay, we'll just go to this page and follow their steps for pitching. But he knew internally that they were looking for someone to do it and they hadn't had that lined up. And because I think of the strength of the outline and the strength of my book proposal, it showed that I had thought through the process and could do it. So, yeah, that's really what it comes down to, is it's not? While it's true that if you don't have a well formed book pitch and you don't seem like you know what you're talking about, it might be difficult to break in, if you hit the publisher with the right idea at the right time, they're always looking to bring new people in.

0:45:43 - Jonathan Bennett
So I guess the question that goes along with that is who should consider writing a tech book. What are the things where you're at in your career or what you've done, the place you've come to, what are kind of the signs that you should think about? Maybe I am the right guy to write a book about X, y or Z, sure, yeah.

0:46:03 - Nathan Freitas
So if you're obviously just learning a topic, then it's probably unless you're a professional technical writer who knows how to learn enough to explain it to someone else. If that's not you, then everyone else I would say. When you reach a middle to almost senior level of competence in a topic, that's a good time to, and where you find yourself mentoring others in the topic is probably a good threshold If you have other people coming to you and you find yourself explaining how to use this technology. So again, if you're brand new to something, then it's probably not the right time because you're still learning yourself. But you also don't have to be the foremost authority.

So if we're talking back when systems administrators roamed the earth and I was one now we have five different names for them, but there was like junior, system administrator and senior. So I would say in that context, if you would label yourself as a senior level person, that you probably have now climbed the learning curve enough on the topic and have enough competence in the topic that you're now training other junior members of your team on how to apply that technology, whatever it is, and you are probably at the phase where if you feel the urge to teach people about that then it's a good time to write a book. I really do think that, other than the desire to do it, the expertise in the topic I mean, that's really what it comes down to to write a textbook A lot more people could do it than probably self assess that they could.

0:47:47 - Doc Searls
So I have some closing, close to closing questions. You're about three quarters away through the show and I'm going to get to those right after this break. Okay, so you've been publishing books throughout the. I think there's a transition that's going on from analog to digital and we live in an almost entirely digital world here. I mean, this is what happened. What we're doing right now is what happened to television and to radio at the same time, because we're both. We're both in video and in audio and this wouldn't have been around 3040, 50 years ago, and now it's almost a standard way to communicate if you're doing broadcast or what used to be broadcast.

So, with publishing, there's like. I spent a lot of time in libraries. There's no shortage of books, you know. So I'm breaking into publishing. An awful lot of people have done it. But there's what? How do you see the publishing industry now, where some of its digital? You talked about the, the, the joy really of feeling and having like a hard cover book, a serious book. We all want to have bookshelves. I got some really tiny ones behind me for those who you can see them, but that's part of what, scattered across three homes, but I like having books around. We all like you know, most of us like having books around. What do you think is happening to the business now and to the, to the field? Libraries, too, are kind of going through a similar set of issues Like what, what do they become?

0:49:20 - Nathan Freitas
Yeah, I mean I think there's a couple of answers there because there's one tech industry focused one, because tech publishing is sort of an entity into itself, and that's one reason I wrote the book is that there are plenty of books on how to write a nonfiction book or how to write a fiction book, but tech publishing is a completely different industry. There's completely different imprints and publishers in that industry. That focus is just on tech books. So where tech books are going, I think there's still a. I think that while there have been periods of time where there's been ebbs and flows in the popularity of tech publishing, there's always a need to learn from an expert the things you need to know to be competent in a subject, in particular in tech, because you find as you go through a career, there's always a need to get new skills and tools to advance your career. If you're interested in advancing your career. And while there are certainly ways that you can do that say for free, online by just reading the documentation that people might put up, the challenge with that is the documentation sometimes is either just covers every topic and not necessarily just what you need to know, or it's not necessarily professionally done or, more importantly, it's not necessarily curated. One of the great things about a good tech book is that you're getting curated information just the things that you actually need to know to become competent in a topic all in one place so that if you want to change careers or just expand your career and learn this new technology that other people are using, you can get a book, read it through and, if it's a good tech book, fill competent in that.

Now, the thing about switching over to ebooks is there's a benefit separate from, like, say, fiction and other nonfiction, for tech in particular. I'm of two minds about it. I'm old school. I mean behind me you see a bunch of old mechanical calculators, right. So I clearly like sort of old fashioned things sometimes, but, and I like the feel of a tangible book, I like the smell of old books. You know I kind of collect certain old books myself, so I like physical books. I like all of my books that I read. I read physical books. However, I also understand the value of, in particular for tech books, having the ebook option, because there's often large code blocks that you need to copy and paste, right, and so that's super valuable for and that's that's, you know, it's a good reason to have both, and I like that certain publishers are making a point to have to offer both options, like, for example, I know with no starch. You buy a print copy, you also get the ebook sent to you, so you have the benefit of both.

0:51:59 - Jonathan Bennett
So I've got to ask real quick because you've definitely gotten the gears worrying in my mind. I do a lot of writing over at Hackaday. All of my stuff is short form. I have some series, but they're still you know. You put them all together and they're short. How do you go from and maybe it's just that the topics I work with don't fit but how do you make the jump from writing short form stuff to long form? How do you, how do you get you know from an article or two to the point of being able to fill up a book?

0:52:32 - Nathan Freitas
Yeah, that's a great question. So you know, on average, let's say that your average article is somewhere between 600 and 1200 words, right, some articles go over that, obviously, but at least for Linux Journal, when I was writing a column there, on average it was 600 to 1200 words, and a page in a book is about 400 words 400 to 500 words, it depends, right? So you could think of, like, an average article would maybe be three pages in a book and your average textbook is 150 pages minimum, right? So that sort of gives a sense of what's involved. So how you make the transition by picking a topic that is definitely much larger than you would fit into an article, or even like a three-parter or a four-parter. Now, that said, a four-part article series on a topic would be a pretty good start for a chapter on that topic. So when I found myself creating a book out of my old Linux Journal articles, for instance, what I ended up doing was collecting all the ones that I thought were still relevant and what I found was some commonality on a lot of the topics. For the most part I was writing about systems administration in some way, or something that would be beneficial from that standpoint. So I realized at least the first book I would write that was a combination of these articles would be focused on that. So that was like step one which of these articles would I set aside? And then step two was then looking and saying, well, some of these have common topics and not everything fit perfectly into a mold. For the most part, I could see patterns emerge among the topics that allowed me to split things up into a couple of different categories, and then those became chapters, essentially.

Now, as someone who wants to write a book from scratch, say, that's again, I keep going back to the outline because that's just so critical. That's where that comes in right. You start thinking about what you would want to write a book about and you start outlining it. And you start looking at the topics that you would want to cover and you start with something. You start with a big vision and then you write the outline and see where you are with that, and then you may have to trim it or you may have to expand it, depending on whether you feel like you have a book-sized thing. And that's again, that's also where traditional publishers can come in. You can pitch them a topic and they might say this is great, except we think that it would be better if we maybe expand the scope to include XYZ or shrink the scope so that it's focused on this particular area, because otherwise it'd be too giant of a book. So yeah, traditional publishers can also really help with something like to help guide you into expanding your topic into a book-linked form.

0:55:18 - Jonathan Bennett
Doc was just saying on the back channel and I think this is interesting. He was told that what, doc 35 to 40,000 words is what publishers are looking at these days.

0:55:28 - Doc Searls
Yeah, I was actually at a thing last week at Harvard where there are a bunch of book writers and one of them is saying, oh no, the new book-link. It used to be like Serious Book 120,000 words, and it was down to 80,000 words. Now it's 35 to 40,000 words and I don't know if that's true or not, but hearing that encourages me. It's like I think of myself as a sprinter like you and not a marathon runner, and I think that's kind of a difference. Now Ann said on the back channel how good is Sprinter becoming a marathon runner? Well, they can't. Let me qualify that. Let me qualify that A good sprinter cannot be a marathon runner.

0:56:13 - Jonathan Bennett
I don't think Ann has a high opinion of marathon runners.

0:56:18 - Doc Searls
Your offensive alignment is not an eligible receiver. I'm sorry. So yeah, go ahead.

0:56:26 - Nathan Freitas
Well, some of this follows a trend that you see in tech publishing, where there have been, and there still are, some publishers that really focus. There used to be that you would judge a book by how thick it was on a subject, and you saw this. There's a lot of series that would add the word Bible to the title, right, and what it basically meant was they were publishing documentation, unedited. Just you know, the goal was to get the thickest possible book, the most pages, and so you would have these tomes. That didn't necessarily teach you what you needed to know, necessarily, but it documented everything in paper form. So you'd have this 500-page book on a topic, and there are certainly some 500-page textbooks I have that are exhaustive on the topic and are incredibly valuable, but for the most part, the more valuable books were those that didn't go. The more pages is better route. And instead, what does it take to explain this topic thoroughly and completely, but succinctly?

0:57:24 - Jonathan Bennett
So I've got to jump in and just real quick make a point. The reason that the publishing the Bible for you know, give your tech subject doesn't work anymore. It's not practical. We have the Internet. All this documentation is on the Internet. You can go look it up. We don't need to publish all the documentation because nobody needs to carry around the physical book of documentation. But what does make sense is to get somebody who's kind of handheld guide through, or, you know, here's my thoughts on or here's a tutorial on, and of course some of that exists on the Internet too. But we don't, you know. You no longer need to publish all the documentation.

0:57:56 - Nathan Freitas
You can just Google for it Exactly. Yeah, what you need instead is some curation of that documentation. It says would you like to learn how to do X? Here's what it takes and here's some examples. And here's things that are practical. Let me guide you through this, as though we were working together at a company and I was showing you what I know.

0:58:16 - Doc Searls
Absolutely. Yeah, it's interesting. I'm thinking well, the Internet has a lot of documentation, but a lot of that is also going to be wrong, you know? I mean, the reason that AI hallucinates is because half the Internet is wrong and it's trained on it. So I don't know where that takes us. But let me just go ahead and try.

0:58:39 - Nathan Freitas
You're about to see something I was going to say it takes us to the editing phase. Right, because that's what even you know my drafts that I finish aren't perfect. Once I've just once I've finished my first draft, there's a whole process of editing and tech editing that go into making a book correct. Because even if I thought something that I wrote was clear and correct, the only way to really know is to have a tech editor come through and try everything that I said themselves and then either understand it correctly and everything worked great, or there was some variation on their system that made it not work and I need to factor that in. Or it's unclear or things like that, and that all, or I made a mistake and it's incorrect. You know there's some typo or something that breaks the command or whatever it is. You know and that's another big factor compared to documentation online, where you know someone may type it up or copy and paste things in, but maybe not has vetted it yet or tested it for correctness.

0:59:32 - Doc Searls
Yeah, so we're down really at the end of the show. Here I'm looking at the clock and we always ask I don't know if, john, you always have one question at the end, and so, yeah, I usually go for that, or not.

0:59:52 - Jonathan Bennett
I usually ask people what the weirdest thing that they've seen someone do with their open source project is, and we usually get some fun answers. I don't know the iteration of that that might work here is what's the weirdest book idea that you've ever thought of?

1:00:05 - Nathan Freitas
Oh, wow, yeah.


I had a book idea one time that very pretty off the wall, where I thought about doing a complete geeks guide to brewing and distilling, where it would walk through not just the process of how to brew beer or cider or any of that sort of thing, but also go the step further in how to distill that into spirits, but also in addition to that because it needs to be legal the process of getting licensed to do that legally and what all of that entails.

But I started doing research into what all of that entails and it turns out I don't have the spare property and the time and expense and all that stuff that actually go through that process myself, in the United States at least. So I kind of canned that idea. Yeah, that's probably the weirdest one was I thought there's so many brewing geeks out there and geeks that also do that sort of thing as a hobby, because it meshes so well all the chemistry and everything that it would be good to write something that not just says how to do it but why you do it this particular way and what's the science behind it. I thought that that would be appealing.

1:01:15 - Doc Searls
Well, I'm kind of surprised that you didn't go straight to something you actually did, which is the Tempus nested knitting clock, which I just put in our back channel. But I mean, tell us about that as briefly as you can, because it's pretty cool.

1:01:33 - Nathan Freitas
Yeah, so I. In January I saw this Hackaday post about this artist who created a clock that knits a scarf over the course of a year, that it does a row. It does a stitch an hour, a row a day, and at the end that drops down a scarf on the floor, and I thought that's incredible, I want one of those. And I went to their site and they said you can commission one from me. And I said oh well, if you have to commission it, you can't afford it. So I need to figure out how to make one, because I want one of those.

And I figured well, it can't be that hard. What is it? It's a stepper motor, it's a knitting machine and some sort of computer to control it. And so that started me down this rabbit hole where, within a couple of weeks, I actually had a functioning prototype that then, after a couple of more weeks, I changed into a smaller knitting machine and learned crash course and 3D design and ended up making one from scratch. And then, on my site, I go through that whole process. I decided to do a full write up, probably a 4 to 6,000 word write up, step by step, with all of my source code shared and all of the steps shared and all the 3D model shared. So now yeah.

I have a 2023 scarf that has stripes. What I did is I customized it. So every I have a black scarf, but as something special happens in the year or bad or good I changed the color to add a stripe to mark that event. And so now I'm most of the way through the year and I have a very colorful scarf, because a lot of things have happened this year that documents 2023 for me.

1:02:57 - Doc Searls
That is exceptionally cool. I'm glad we worked it in. We are at the end, or maybe beyond. So very quickly, what's your favorite text editor and scripting language, even if you've already said some of that, All right.

1:03:10 - Nathan Freitas
Well, it's Vim. It's Vim all day long. I've been using Vim forever and probably bash. I probably find myself using batch more than anything else.

1:03:20 - Doc Searls
I never know who's going to what's going to get the bell, but the bell does show up. What will trigger the bell? Okay, pal, thanks so much, man for being on the show and we'll definitely have you back.

1:03:33 - Jonathan Bennett
Oh, it's been my pleasure.

1:03:33 - Doc Searls
You'll have to show a scarf next time too.

1:03:35 - Jonathan Bennett

1:03:38 - Doc Searls
So, jonathan, that was good. Oh, that's great.

1:03:40 - Jonathan Bennett
That's all the fun. Now, are you going to write a book? You know I've thought about it in the past. There's a lot of there's questions that would need to be answered, like how what hack a day would feel about me writing a book and maybe using some of the articles that have been published there. But if I really come across a winner of a topic, you know it might be a thing that will happen, right.

1:04:05 - Nathan Freitas
Are you still the owner and you're granting them a copyright, or are they the owners of the things that you write?

1:04:12 - Jonathan Bennett
You know, I'm not. I'm not actually sure exactly how that's set up, but even even above and beyond that, I would, I would want to clear it with them first and get their opinion on the idea. But yeah, that is a good question and I'm sure you have a part in the book where you talks about copyright and licensing and all those things I do, I do.

1:04:32 - Nathan Freitas
Yeah, that's another 10 minutes to go into that. Yeah, that's in chapter three, when you're pitching, I have a whole section on the book contract and things to look out for in the book contract.

1:04:42 - Doc Searls
I want to know how many more books get sold because of the show. So it's time for you to do your plugs, jonathan, and we're already like plugged the heck out of hackaday, but why not?

1:04:55 - Jonathan Bennett
Okay, so there is. There's hackaday security article goes live every Friday morning. There's also the untitled Linux show, which is a club twit exclusive, and if you're not on club twit, you really should. It's basically the price of a fancy cup of coffee per month. I mean, come on, you get access to the discord, you get access to ad free shows, you get access to cool shows like the untitled Linux show. We have a blast there. That is basically it. You can buy me a coffee if you want to, over at. Buy me a coffeecom, but just consider that a tip jar. But that's it, and boys, it was great to be here.

1:05:28 - Doc Searls
So I get to plug next week. It's Michael Hoffman, known as Hoff, at the Spatial Computing and AI and open source stuff, and you can find out more about him in advance at IQXRcom. So anyway, that's coming up next week. Until then, I will remain Doc Searles and this will remain Plus Weekly. We'll see you then.

1:05:51 - Leo Laporte
Listeners of this program get an ad free version if they're members of Club Twit. $7 a month gives you ad free versions of all of our shows, Plus membership in the club twit discord, a great clubhouse for twit listeners. And finally the twit plus feed with shows like Stacy's book club, the untitled Linux show, the GizFiz and more. Go to, and thanks for your support.

All Transcripts posts