Menu
▾
▴
Re: [Amsn-devel] Updated FAQ
|
From: Youness A. <kak...@ka...> - 2005-11-04 03:45:06
|
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 te...@ho..., 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 <cle...@gm...> 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 > Ams...@li... > https://lists.sourceforge.net/lists/listinfo/amsn-devel -- KaKaRoTo |
