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
