Hello, Thanks Youness for the lengthy list of comments. I definately appreicate it, although I don't have time to read it in depth at the moment. I will take them into consideration when I come back tomorrow to edit more.
I just wanted to make you aware that this was definately a rough draft. I wanted to show everyone that I have been working on it, and this is what I have, instead of simply saying "I'm working on it", without some good hard evidence. Everything was just thrown into a long "laundry-list" of what should be included in the FAQ. When I get more time, I will go through it throughly and make it much more attractive and do a massive cleaning. I have some nice ideas for it, so we'll see what comes out of my ideas :-) If anyone else has comments that they would like to add to Youness' massive email, please let me know, and as I said... I appreciate the feedback :-) Thanks, ~Lee On 11/3/05, Youness Alaoui <[EMAIL PROTECTED]> wrote: > Hi there.. > Thanks for your hard and appreciated work. I don't have much time (as > usual) but now, I can't do much since I just came back from the hospital > (one nail got cut off my foot) so I have to do something to forget about > the pain... > I'll be writing this email at the same time as I'll be reading the FAQ... > and I'll post any comments I have so far... so here we go : > > first, I noticed that the layout isn't very attractive.. maybe change it > to something else.. another font, smaller fonts, questions maybe in bigger > font than the answers but not that much... search for a few FAQs on the > internet and choose the one that you (and your eyes) feel the most > confortable reading... now it just looks like a load of text thrown on a > page... > > secondly, I needs the most important thing in a FAQ : a TOC (Table of > Content)... > Without it, you're screwed.. noone will be able to read the FAQ... > > Humm.. I just tried the pdf version (I was reading the html one...) it's a > little bit nicer.. so this means the html generator should be different... > main problem you can see is in the "Requirements" section... I don't know > what you used, but if it's not openOffice 2.0, then you should upgrade!! > (hey, I was using RC2, I just checked openoffice.org website and 2.0 is > finally released! go get it!) > > ok.. I would suggest "better" grouping.. the top 2 questions have no > section.. it should probably be "general" or "preface".. > > The question "what is required to run amsn" sounds too much of a question > for "amsn's requirements".. I would rephrase it into a more > "user-friendly" question.. something like "what do I need to run amsn?" or > "Does amsn work right out of the box?" (if you use the latter question, > you should talk about compiling amsn and using binary packages... so I > would suggest you just use the first one) > About that same question, first, I don't like the "You don't need those > two if ..." in bold and between parenthesis... I would suggest you use a > good sentence to make it clear... use the active voice instead of the > passive voice... like this : > If you're using windows or Mac OS X, amsn will run right out of the box if > you download the official packages. > If you're using Linux, you will need Tcl/Tk 8.4 or above in order to run > amsn, but that package is usually installed by default on most > distributions or can be installed as a dependency if your packaging system > supports it (rpm, deb, [list all known packages that we have for amsn]...) > You don't need more than that because amsn 0.95 does NOT need Imlib > anymore.. so you should remove it from that page... > (little typo that probably will change if you rewrite this question.. > "theses files" => "these files") > > Humm.. I though of something.. maybe give a number for each question... > > ooh oh... I just noticed the next question is "what do I need to run > amsn"... why two questions rephrased differently ??? humm.. ok, the > content is good.. one thing though : TkCximage is MANDATORY... so it must > be compiled before use... also, tcl.sourceforge.net... nope.. give them > the http://tcl.tk link (having clickable links would be nice too).. > also, I would suggest you say "you NEED all this".. not "if you want > special features..." talk about tcltls and assume the traydock, tkcximage, > webcamsn are all going to be compiled... > don't talk about linphone please... we dropped linphone support.... I > don't know if you talk about it later, but please don't... only one > question : > Q : How can I make videoconferencing (linphone) work, or where to ask > questions about it > A : Don't make it work, don't try it.. if you do, use it AT YOUR OWN > RISKS. aMSN team doesn't support linphone anymore. > > Next question, the "NOTE" is not 100% good, I would suggest instead of > giving a list of 3 consoles, just give ONE.. because some people will say > "I tried running console/konsole/terminal and it says "no such > command"..." I will suggest you propose "xterm" since it's an X tool, so > everyone has it!! just say "all command should be typed in a terminal, run > the "xterm" command to get access to a terminal" > Also don't say "I will tell you... I mean..." say "when I say this, do > this..." don't be nice, be harsh and direct. > The list of "ways to install" are not correctly set.. you should go with > the simplest.. I would say Windows Installer, Mac Installer, Linux > Installer, Linux packages (.deb, rpm), tarball... DON'T TALK ABOUT > CVS!!!!! We don't want every 2cents user to go and try CVS.. leave it to > those who know how to click on "SF project page" and click on "CVS".. and > there are nice instructions there... it would cause too much problems to > have users go with cvs... > I would also suggest for each installer a screenshot to show how to do > it... (easy for the "isntallers" but for tarball, you would take a > snapshot of xterm with the tar command, the cd and the wish amsn &, don't > forget to remove part of the output of tar, leave maybe 3 lines before and > after... or disabl outputting the filenames extracted (the -v option?) ) > Put the commands to type in a frame (like the gentoo install howto if it > didn't change) or like the grey frames in some pages of the Wiki... > in the tarball installation, you say "I order ..." it should be "In > order".. little typo.. :) > If you say "just download the tarball"... you should give the link to it > too.. > don't say "go to the new directory (...)" but "go to the newly created > directly, which would be ..." > If you do a "amsn-<verson>.tar.gz" you must specify that <version> > represents the version number and give an example (for example > amsn-0.95.tar.gz" > remove the whole CVS part.. keep it somewhere in the wiki for users who > might need it... > When you talk about the linux installer, the "right click then choose > Permissions"... you should specify using which file manager... if you list > one, then you should list how to do it for all file managers... if you > don't want to do it, then don't tell them how to do it graphically... I > suggest you always talk about how it should work when using xterm. > Dont say 'cd /path/to/amsn' ... users want a step-by-step tutorial... it > should be 'cd ~/ && mkdir amsn && wget http...' you HAVE to tell them > where to put it..some people might think that amsn won't install if it's > not located in a folder names /path/to/amsn ... This is even more true > since you say "here's an example" > for debian it's good, but you say "download *.deb" the *.deb might confuse > users and they might think they should find and download ALL .deb files in > amsn's release system... > don't talk about alien... you're saying "if we're slow..." no.. because we > won't be, we MUST NOT BE... you can't say in the FAQ that we have > problems.. we should be "perfect".. > The gentoo one is the most perfect one of all :) and that's my last point > actually, that's what every thing should look like.. don't talk about yum > and rpm, or apt and dpkg and alien.. no, show the users only ONE way.. and > show them the simplest one... You might want to put later in another > question : > Q : The repostiory I'm using doesn't have amsn, how can I install it ? > A : Go get the "amsn 0.95 Debian package" [The name as it will appear in > the website actually] and type : dpkg -i amsn-0.95.deb > > Last thing about install, remove it from the FAQ :p.. hehe, sorry, but > it's not a FAQ... it should be something like this : > Q : How do I install amsn ? > A : Follow the installation instructions from http://.... > that should do it... don't overload the FAQ, make it simple and easy to go > through for user... > > About the traydock, make it more modular.. if you list something like > this, (and for everything else), you should use bullets, : > * Mac doesn't support traydocking for the moment [Or is it automatically > supported by Mac ?] > * On Windows, the traydock is automatically used, if it's not, you can > enable it from ... > * On Linux, the traydock is automatically used, if it's not, you can > enable it from ... > > Don't talk about how to compile the traydock... assume users will use a > binary package... you could have a "FAQ for users who compiled their > amsn".. that could also be nice!! > You could add something like this : > Q : I don't see the traydock even if I enabled it, what's the problem ? > A : Make sure the file msn/utils/linux/traydock/libtray.so exists [for > linux here!!!], if it's not, make sure you download an official package of > amsn. If you compiled amsn yourself, please follow this FAQ [link to the > FAQ with compile Q/A] > > Don't say "do a make clean".. how can you assume the users have the > sources of amsn or a makefile ? what if they used a binary package. > > Don't talk about composite extension, it's now fixed > > the huge questions that comes after that is not good.. don't put output > like this in the question... > change it to something like : > Q : I'm sure I have compiled the latest thing but I don't see the changes > refelcted in amsn... > A : If you don't see your changes, maybe the compilation didn't occur > correctly, type make clean all to force the recompilation of everything. > (note that this should go in the CVS FAQ file) > > The other huge question with the ./configure output shouldn't be like > that.. remove all the ./configure output and keep it like "if the > ./configure exists with the error : "error : could not find...", what > should I do ?" > > The next question has output in dutch or whatever... don't leave it like > that!!! remove everything and say "if it exits with ... Command not found > error" > > Remove the "how to install imlib" imlib is not needed anymore > > next question about the invalid color bug... DON'T EXPLAIN the cause... > don't say abook.xml if you don't give the full path to it... don't say > remove your configuration... answer simply with "delete the abook.xml file > from your profile directory.. assuming your email is [EMAIL PROTECTED], > type in xterm : rm ~/.amsn/test_hotmail_com/abook.xml" and that's it.. not > too much info, don't confuse users and don't give half answers either... > that answer would have given you two questions "what's the abook.xml > file".. where are my config files...without talking about the explanation > of the bug..I myself didn't understand it... > > The questions should be questions, not emails "Hello. I want to...".. no > make it into a simple sentence that is a question with a question mark > like "How can I ..." > about the mim2mpeg.. remove that... it should be cam2mpeg and it's > completly outdated.. it doesn't work now with the latest libmimic AND it's > nowhere to be found.. it has been removed and you won't find it... I have > it on my pc and I began porting it to the new API, but I didn't finish... > > Again there's a huge email... remove the "I installed amsn on a friend's > pc..." make it into "Where can I find a tcltls extension that works on 64 > bits processors? " > > Great, perfect for linphone-im question... make the answer non-bold.. but > anyways you'll fix it when fixing the layout... > > QUESTION "CAN I SEE WHO BLOCKED ME?" DON'T ANSWER YESSSSSSSSSSS... IT'S > NOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO > > how to change display pic, use the simplest way, don't say click on your > nick, and give an example (it was a good initiative for giving an > example).. just answer this : "Click on the 'aMSN' menu from the contact > list, then on 'my status'and from the new menu that appears, click on the > before last entry 'Change Display picture'" > Don't explain all the methods to do it.. unless for install where one > method might not work (in which case, like I said it would be a new > question "what to do if this didn't work").. the question isn't "What are > all the places in the code where you call the function that opens the > change display picture dialog?".. it's just "how can I change it..." > answer "do this.." at the very last, you can always add at the end "For > more information and other methods of doing this, see the Documentation of > aMSN at http://..."; don't forget it's a FAQ, it's not a doc... > > again, don't talk about compilation for the webcam... you should just say > "click here..." assuming it's compiled.. > > again.. the same as above... say that if it seg faults (say if it exits > unexpectably because users might not use the console and don't see the > "segmentation fault" message) make sure their webcam driver is stable, if > they use the pwc driver, they should enable X option (I don't know if it > was added in advanced prefs...) I'll have to confirm and reply to this > later... > > next question.. answer "we do not support JPEG webcams but we will in a > near future".. don't talk about farsight and don't apologize!!!! > > Your next-next question is about input.. it should be grouped with input > questions, not webcam questions, other than that, it's perfect. Simple, > precise and direct! > oh.. no, the question is a bit long.. make it into a "I'm not able to > read/write chinese nor japanese characters, how can I make it work with > amsn?" (it's not a specific problem to gentoo, emerge.. > you also don't need to say "this solution will not work".. you could at > least have the "change your encoding" as the first solution and the next > question "I tried changing the encoding but it didn't work"...(again, it > should be a question, so you would it "it didn't work. What can I do?" ) > > Don't talk about the "No grabber available" bug because it's fixed it now > shows a message saying "you don't have any webcam" > > Next question is PERFECT! :) > > > oupss.... I have to go now... Anyways, I commented on half of the FAQ but > I think you got the point on how to do it, change it... > Ohh.. one last thing I was waiting until the end to tell you... when you > mix text with output.. it would be nice to differentiate them... like > " > When I do a ./configure, I get this output > .... > .... > .... > what does this mean..." > > I usually try to read carefullly not to miss a sentence from the > question... besides the fact that I said, don't put huge things in the > questions, but you might want to put output in the answer, separate it > with a frame and use a smaller font... > > I did a lot of documentation at my job and I kind of know how to write > good doc.. but I never done any FAQ.. so I just hope my intuition on this > is right... > everyone is of course welcomed to give comments on the FAQ and/or on what > I commented... > Lee, I hope you won't get mad at me saying "I did such a good job and then > I have to redo everything!!!", don't get me wrong, you really did a good > job, but now, let's make it a great job ;) > Thanks for all your help and for getting involved. > GerScarabe can help on the FAQ now, I would suggest you number the > questions and divide the work... > I will now summarize the main points I said : > 1 - Change layout > 2 - All questions... make them small, simple, direct, to the point > 3 - Simple, short and direct answers... don't give multiple choices and be > clear > 4 - Create a 'normal FAQ', a 'CVS FAQ' and a 'compilation FAQ' ... You > could also have a 'Windows FAQ', 'Linux FAQ', 'Mac FAQ'... and don't > hesitate to put in the same question or same question AND answer in > mutliple FAQs... > 5 - Remove anything outdated > 6 - Assume the users don't have the source code, they can't just > "recompile" and they all have binary packages with everything pre-compiled. > 7 - If you list something (like different answers for different platforms) > use Bullets > 8 - Good luck :) > > I think that's all, keep it up! > > KaKaRoTo > > > > > > On Thu, 03 Nov 2005 18:11:26 -0500, Lee Olson <[EMAIL PROTECTED]> wrote: > > > Hello, > > > > I've been updating the FAQ. Here's a preview of what I have so far. > > (3 different forms for your convenience): > > > > html: > > http://maclc-level-three.com/beast/aMSN/documentation/faq.html > > > > openoffice2 document (oasis opendocument text): > > http://maclc-level-three.com/beast/aMSN/documentation/faq.odt > > > > pdf: > > http://maclc-level-three.com/beast/aMSN/documentation/faq.pdf > > > > > > NOTE: This is only a rough draft and I am aware that there may be > > duplicate questions and inconsistencies throughout the documentation. > > If you have time, please take a look through it and send me your > > edits. > > > > Happy reading! :-) > > ~Lee > > > > > > ------------------------------------------------------- > > SF.Net email is sponsored by: > > Tame your development challenges with Apache's Geronimo App Server. > > Download > > it for free - -and be entered to win a 42" plasma tv or your very own > > Sony(tm)PSP. Click here to play: http://sourceforge.net/geronimo.php > > _______________________________________________ > > Amsn-devel mailing list > > Amsn-devel@lists.sourceforge.net > > https://lists.sourceforge.net/lists/listinfo/amsn-devel > > > > -- > KaKaRoTo > > > ------------------------------------------------------- > SF.Net email is sponsored by: > Tame your development challenges with Apache's Geronimo App Server. Download > it for free - -and be entered to win a 42" plasma tv or your very own > Sony(tm)PSP. Click here to play: http://sourceforge.net/geronimo.php > _______________________________________________ > Amsn-devel mailing list > Amsn-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/amsn-devel > ------------------------------------------------------- SF.Net email is sponsored by: Tame your development challenges with Apache's Geronimo App Server. Download it for free - -and be entered to win a 42" plasma tv or your very own Sony(tm)PSP. Click here to play: http://sourceforge.net/geronimo.php _______________________________________________ Amsn-devel mailing list Amsn-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/amsn-devel
