Hey! I, for one, love technical books that cover a bit of everything (history, concepts, internals, walkthroughs, special cases with examples.) It doesn't have to go into great details about a topic if the section ends with some pointers to locations where to find the missing info for the reader (online, or another book.)
IMO API descriptions should remain an online documentation, exclusively. The same applies for everything that might very likely change in the future. My two cents. On 24/09/2011 16:04, David Baelde wrote: > Dear all, > > Thanks for your input, it's really interesting to hear how you feel > about liquidsoap and the learning of it. In this mail I'll summarize a > bit what has been said and add my own advice. > > Clearly, an ink-and-paper book is exciting, it would feel "real" and > increase awareness. Today, it looks like this has to go with an ebook, > but this doesn't seem to constrain the choice on how to publish -- we > should probably take it into account for the choice of technology, > though. > > A question is whether we need a more linear form than the current > documentation. Hypertext has its merits but a linear form is needed > for a PDF, an ebook or a real book, and it allows a different way to > read the content (on the subway, offline, etc). This is not a big > issue: in my opinion, the linear and hypertextual documentation need > not be separated, they could come from the same content with minor > tweaks. > > What's really unclear is what content is needed. Some people miss > step-by-step tutorials and ready-to-try examples, others would like to > understand the guts of liquidsoap to master advanced applications, > perhaps through the detailed presentation of cool advanced hacks, some > other people would like to read about the history, people and ideas > behind liquidsoap... I don't think we can accomodate all that in a > single book! In addition, covering some of the advanced topics will be > tricky because liquidsoap is still changing in some areas. > > To me, it makes sense to keep developing the current online > documentation. I do not see a good reason to run the book separately, > unless there is a real possibility to get an editor, and that editor > forbids us to make content available online. I wouldn't speculate too > much on that, and put the priority on getting documentation available > to people. There are a few articles/chapters that I'd like to write, > I've already delayed that too much and the book project shouldn't > delay it more. > > Finally, the question of which technology to use is interesting. I > really like the djangobook, because it allows easy feedback from > readers. However, it doesn't seem easy to benefit from the technology: > it's not open-source, and there doesn't seem to be an online platform > offering that kind of service. I don't think that the input format > (latex, other markup, be it our own or not) doesn't matter much, but > having a better PDF (and ebook) output would be useful. > > To conclude, my opinion is that we should concentrate first on the > online documentation: expand it, organize it, perhaps change the > technology. It seems that the most important thing at this point is to > get more liquidsoap experts to support the growing community. What I'd > like to do is write as much as possible (I haven't written any doc in > a while, that's bad), write beginners tutorials, doc about advanced > features, examples, any kind of doc. And in parallel, organize this in > a linear form when relevant --- for example, all the pages about the > core concepts of liquidsoap (clock, source, request, protocol, etc) > could form a chapter. > > Cheers, > -- > David > > PS: There was a suggestion to run a forum rather than create a book: > this is another issue which has been discussed before. The developers > do not want to administrate a forum, and we do not have time for > providing more support than what is already done on the mailing list. > The point of the book (and documentation in general) is to make it > possible for other people to become experts and help others. > > ------------------------------------------------------------------------------ > All of the data generated in your IT infrastructure is seriously valuable. > Why? It contains a definitive record of application performance, security > threats, fraudulent activity, and more. Splunk takes this data and makes > sense of it. IT sense. And common sense. > http://p.sf.net/sfu/splunk-d2dcopy2 > _______________________________________________ > Savonet-users mailing list > Savonet-users@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/savonet-users -- best regards, okay_awright <okay_awright AT ddcr DOT biz> [PGP key on request] ------------------------------------------------------------------------------ All of the data generated in your IT infrastructure is seriously valuable. Why? It contains a definitive record of application performance, security threats, fraudulent activity, and more. Splunk takes this data and makes sense of it. IT sense. And common sense. http://p.sf.net/sfu/splunk-d2dcopy2 _______________________________________________ Savonet-users mailing list Savonet-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/savonet-users
