+1. Add parts
Since the document targets multiple audiences, the heading additions let the reader chose the content relevant to their role. Paul ________________________________________ From: [email protected] [[email protected]] on behalf of Dino Farinacci [[email protected]] Sent: Saturday, October 05, 2013 7:25 AM To: Noel Chiappa Cc: [email protected]; [email protected] Subject: Re: [lisp] Intro doc - to split, or not to split I vote for the Part I/II option in one document. Dino > On Oct 5, 2013, at 7:05 AM, [email protected] (Noel Chiappa) wrote: > > At the just-concluded Interim WG meeting, there was a certain amount of > discussion of the idea of splitting the Introduction document into two roughly > equal-length document (the split being just after 'Examples'). > > The basic rationale for splitting it was that it's too lengthy (and detailed, > towards the end) a document to give to someone who just wants to know > 'something about LISP', but that the first part is not a bad introduction to > LISP to those who want to know 'something about it'. > > (Albeit that the focus is 'what are the main moving parts _inside_ LISP, and > how do they interact', rather than 'this is what LISP can do for you', or any > number of other potentially useful documents). > > There are good points both ways (two documents, and one), and we had a certain > amount of indecision about what to do. > > Since the document is _already_ structured as 'a shorter adocument within a > larger one' (with the explicit notation that people can read just the first > part, if they want a 'brief intro to LISP'), it seemed a natural move to > _actually_ split it in two. Other than a certain amount of editorial work > (inter-section references would have to be fixed), it needed little work to > accomplish. > > So we agreed to do it. > > Hoever, on thinking about it a bit, I decided that while that would result in > a perfectly find stand-alone first document, the second would be problematic. > To use an analogy I came up with, it was rather like a decapitated body - it > was so obviously the second part of something, and there was no good way to > make a standalone document out of it. (Imagine the title... "Intro: Part II"?) > The only solution seemed to be to put the head back on... > > People seemed to understand, and agree, that there was a problem with the > second half as a stand-alone document, so we then decided we'd leave it as > one. > > We further decided that we'd emphasize the two-part nature of the document by > formally splitting it into "Part I" and "Part II". > > What do people think of this? Is everyone happy with it? If someone would > prefer two, can they see a way to make a viable document out of the second > half? Speak! > > Noel > _______________________________________________ > lisp mailing list > [email protected] > https://www.ietf.org/mailman/listinfo/lisp _______________________________________________ lisp mailing list [email protected] https://www.ietf.org/mailman/listinfo/lisp _______________________________________________ lisp mailing list [email protected] https://www.ietf.org/mailman/listinfo/lisp
