Hi Oskar, I'm copying this response back to the group because others may wish to add a view. (Comments that start with >> were made by DiG, comments that start with > were Oskar's responses.) >> I am finding some of the syntax hard to understand in places. > What kind of syntax, the computer syntax or my writing syntax? It was your English I had trouble with. > English isn't my "main language" I am so glad you said that! :) I couldn't think of a polite way to ask. This is not a problem. Now I know this I understand how to best help. Spelling is not my strong point, but when I concentrate I can get the words in the right order. >> The document also changes from first person to third person in places. > Ugh.... at work I am forced to write in first person, but when I write > "as I wish" I generally tend to write in third person. Don't ask me > why. Which form would you think is the best to use? First or third? > Personally, I think third person sounds more ... "ellegant", but I am > in no good position to make a judgement since english isn't my main > language=). Consistency is my only issue. Writting everything in third person can be hard when documenting and distances your from the reader. We are fighting more than one battle here. 1. We must educate the user. 2. We must make the user our friend. We are writting this document out of love not because we see a huge pot of gold at the end. Yes, we might get to a huge pot of gold but that is not our main focus. We want to partner with our reader. They in turn will become passionate about sharing what we already know with other people. >> Who the intended reader? This was unclear to me. > The introduction/preface in general needs to be a little bit reworked. > To be fairly honest, I don't know who the intended reader is. Ok, I can help with that to start with and offer some suggestions. >In general, it should be someone with medium through advanced knowledge in > TCP/IP and networking, as well as in Linux administration. I disagree with both those points. I will explain why a little bit further down... > I don't think it will fit in for anyone who barely know how to set up > a network under linux. 90% of these variables are very fragile and may > make things go totally "tits-up" if you excuse the expression. I also disagree with the two points you have made above. 1. Foundation Stones. The area you are talking about forms part of the foundation stones of Linux. 2. Target Audience. The target audience should be anyone with a reasonable grasp of network concepts (ie two or more computers linked together is known as a network). 3. Information Leads to Understanding. Publishing the information with a good explanation will lead to the responsible reader making an informed decisions. An educated user won't harm their systems if we provide them with enough information in a format that leads them to understanding it. 4. Our role. Our role is to provide the information. Having provided the reader with the information it is the users role to decide if they are confident to use the information to make changes to their system. We are stewards not wardons. >> At the start of the document you have made a number of assumptions >> about your reader which makes the opening very hard to follow (I had >> to read it 4 or 5 times.) > > Hmmm, where do you mean? What kind of assumptions?=) Let me know, and I > will try to take care of them. I will redraft the opening for your consideration. I think that would be quicker than my attempting to explain my thoughts. >> At 32 I'm a programmer who's worked with IT for more than 15 years but >> mainly with Microsoft products. > Well, I'm 23 and been in IT for 5 years. Not impressive I assume, but I > try my best, and writing means that I learn much much better than any > other way. Thank you for the background. Like you I try my best in a less than perfect world. I choose to share my background with you to help you work out in your own mind how you can best use my skills in your project. >> I have written many instruction manuals that have been used by people >> older than my parents with very few computer skills. >> >> I found your document very useful so far because it fills a void for >> people like me who have a very good technical back ground and common >> sence but are new to the linux side of things. > > Thanks, very much appreciated:). In general, I would say that these > variables are not meant for the "new comers" really. To put it in the > words of Alexey Kuznetsov, "the algorithms are only understood by a > handful of people in the world, and people should not need understand > them. Some of the variables should not even be touched without the > expertise of these persons". System administrators often make the wrong changes to a system because they don't completely understand what the setting does and don't know that the setting they are changing shouldn't be changed. A common mistake made by administrators is to change one setting with out making changes to another. This happens because they don't realise the impact of what they are changing. > I wish I could claim to fully understand the algorithms, but I don't. I > understand them partially, and I try my best to explain the basic > meaning of them. But.... there is no sense really in trying to explain > what the tcp_fack variable does from scratch to a complete newbie, who > has never used or read about networks or linux before. He should start > with something more basic, such as TCP/IP Network Administration and > Linux Unleashed before trying to understand this text. As expressed above, this area forms the foundation stones of the system. When a good music teacher starts teaching you to play they start with scales (a series of musical notes). I agree this is not a starting point. However the newbie should be able to start here, understand the information and then take that with them as they move on. Cheers DiG _______________________________________________ LARTC mailing list / LARTC@mailman.ds9a.nl http://mailman.ds9a.nl/mailman/listinfo/lartc HOWTO: http://lartc.org/
