Comodo Firewall - Help for Users written by Users! Volume 1, 2, 3

[Guest]

[xiuhcoatl]

My thinking is go into KAnders section 1 & 2 Then have a section on a basic setting For the average joe In this secton create a part on
   Alerts
      What are they
          Learning mode alerts
          Other alerts
      How do I respond

Just some quick thoughts lots of work to do
I will post an edit To Kanders TOC some time tomorrow.
Just to show and discuss

Thanks for every ones input so far. Looks like we have some work to do to get this right but with the work divided it could go suprisingly fast.  Depends on if it's a quik primer or a compilation of the forum knowlege I go for athe later with a prime included and possiblly Seperate as well so as not to scare away the less experienced users

Just my thoughts OD

Keeping it simple?  Don't go straight for references to DHCP, DLL-injections, COM/OLE Automation attempts, etc.  Average user doesn't know what those mean, and doesn't care.  Only wants it to work. ......

Problem may be, average computer user may not be the same as average Comodo user.  Question is , if not, why not?  If not, should it be?  I think that if Comodo wants to secure desktops, they need to be able to reach that group effectively, but that group is going to be a tough nut to crack, IMO. 

You also don't want to sound like a complete numpty, as if you're explaining to a pre-schooler (who probably knows more about it than you anyway, LOL).

I think the use of word illustrations like kander mentioned is good, too.  I don't know if it's this way the world over, but I have found in a lot of places "car" illustrations are well-understood.  Other commonalities, such as the "house" illustration Melih always uses, are good places to look.  If everyone instinctively relates to the illustration, it will help them understand (as long as the two ideas are well-correlated).

LM

[kander]

Guys,

Just checking in on what's happened throughout the day. Here are some random thoughts that popped up while travelling today:

1. We could use Google Docs for collaboration. This gives us the advantage of being able to work in tandem, and everyone always having access to the most recent version. Also makes exporting to .doc and other formats pretty easy. Disadvantage is that it's less open for review than a wiki, and that some users may have privacy concerns regarding Google.

2. As others have said: "For Dummies" is probably a trademark. Why risk having to change the name later if we can try to come up with something original and copyright-safe now?

3. Regarding copyright: What about it? If we write something as a collaborative project, it's basically impossible for Comodo to do anything at all with it unless ALL authors and editors agree to release their works either to Comodo or under a free license. Personally I strongly favor a free license over handing over rights to Comodo. I believe it to be important that we get this straight from the get-go, to avoid major headaches down the road. How about a simple condition-for-contribution: "Every editor must send in a public message declaring that he understands and accepts that any contributions made to the Comodo Guide are made under the GNU Free Documentation License, and can be distributed and altered (among other things) without consulting him/her" ?

4. I agree with the sentiment that Toggie's ToC gets too technical for an introduction guide.. I do like the thoroughness of it, though... looking it through, many points are present which are important, but don't have a particular task associated with it (for example: "Tray Icon"). It definitely does not seem like a good idea to have all this jargon in the ToC at the beginning of the book - perhaps having the ToC go down to the second level would help? It avoids common lists seen in many items (Add, Edit, Remove, Purge, Groups) for all Files sections, for example. And what's there to tell about 'Remove' anyway? You will probably end up with microsections that contain little to no information beyond what can be summarised as "Using the buttons on the right side you can add, edit and remove files from this list.", after explaining what the list is.

It does seem we have some great momentum going here, people.. let's keep this ball rolling!

[panic]

Also another idea we might utilise is: you know when someone walks out in a department store, the alarms go off, cos they still have the tags.. thats like firewall outbound protection.. Nothing can make a call without alarm bells going off Another concept that users might associate with....


Melih

Just one idea to contemplate - IMHO the best manual I've ever seen came in three parts. Part I was for Mr. and Mrs. Average, and was written in the "see spot run" style. Part II was aimed at intermediate users who had a grasp of the overall concept and some of its implications and Part III was written for advanced users and was written appropriately.

These weren't delivered as three parts within the one manual. They were three discrete manuals, written by three separate teams but they were each oversighted by a central body for consistency. The thinking behind this was that the user could determine their own level of expertise and use the appropriate manual, without having to try to find their level of comprehension within a topic within a chapter. Usability tests at a Welsh university on user-documentation (as part of a UI design project) seemed to confirm that this method let the users learn quicker and easier with less confusion and "side tracking". As the user became more experienced, they "graduated" to the next manual.

An obvious comparison (obvious if you're REALLY old!) is the user adjustable UI that was user in PC-GEOS. The user could tell the OS they were a beginner and the options and functionality in the OS and supported apps were reduced. When the user becvame more confident, they could adjust the UI to the next level, exposing more options and functions.

If this is a book for the users, let's do it from their perspective - all of them.

As the old saying goes, before you can appreciate a man you must walk a mile in his moccasins. Then, you'll know what it's like to be him, you'll have a new pair of shoes and be too far away for him to chase you.

Just a thought,
Ewen :-)

[panic]

I will check, but i don't think so. cos "comodo" is our TM and dummies is a not a TM word etc..
lets continue as is, i will check if its a no go, then we will change.. until then though... lets stick with the name.

thanks
Melih

It's a definite NO-GO Melih, as it is being used as part of the title of an instructional book/video/media, aimed at explaining something in a simple manner aimed at the common man.

I've asked a few lawyer mates and they all agree, you'd be hanging yourself out to dry on tnis one.

Ewen :-)

[panic]

This way we can make some assumptions, like the user knowing that the internet consists of a bunch of computers talking together, in the chapters that follow.

In writing, as in life, NEVER ASSUME! The easiest way to find out if something is fool-proof is to give it to a fool. They will think of a way to break your design or misconstrue your words that you or I simply couldn't contemplate.

As an aside, I think we should also have a transition guide for users moving from 2.4 to V3.

Ewen :-)

[kander]

Ewen, I have to disagree with you. In life, certain assumptions have to be made. You assume good faith in people, you assume they speak the same language, you assume that your interpretation of their intent is correct, etc.

Same goes for writing technical documentation - at some point you have to begin making assumptions about basic knowledge regarding computers. Some lame examples include assuming the user knows "What is a mouse? How do I turn my computer on?", etc.

The problem is: Where do you draw that line? What I proposed in the bit you quoted (slightly out of context, IMHO) is to use the first chapter to deal with these assumptions. Explain everything as clearly as possible in the first chapter - give context to the problem we're solving, etc. By doing this, we'll won't have to rehash the entire 'The internet is really a bunch of computers talking to eachother' paradigm in each and every chapter (which is the same as saying we can ASSUME that they know that).

Because the first chapter would be explicitly refered to as a context-building chapter, we can then further assume that if the user does find himself confused when reading Chapter 11, he can find his way back to safe ground earlier in the book to get acquainted with the basic concepts we deal with, possibly with pointers here and there.

I agree on the transition guide. Which would be better: having this in the Installation chapters, or in with the more advanced stuff?

[kander]

After mulling it over for a bit, I can find nothing against the multi-stage manual proposal.. well, apart from it being slightly more work to create and maintain three (possibly more?) document, and not having a single source of information.. but those problems are not insurmountable. Especially the argument that it reduces side-tracking (something easily done in technical topics) is a strong one.

Would you happen to have a link or other reference to the Welsh university's results (name of the research group?) ? I'd be very interested in them for work-related reasons

[Quill]

Kander wrote:

1. We could use Google Docs for collaboration. This gives us the advantage of being able to work in tandem, and everyone always having access to the most recent version. Also makes exporting to .doc and other formats pretty easy. Disadvantage is that it's less open for review than a wiki, and that some users may have privacy concerns regarding Google.

I'm unfamiliar with the workings of Google Docs as I've never had the need to use them. However, the idea may be sound, providing they are easy enough for everyone to get up to speed quickly.

4. I agree with the sentiment that Toggie's ToC gets too technical for an introduction guide.. I do like the thoroughness of it, though... looking it through, many points are present which are important, but don't have a particular task associated with it (for example: "Tray Icon"). It definitely does not seem like a good idea to have all this jargon in the ToC at the beginning of the book - perhaps having the ToC go down to the second level would help? It avoids common lists seen in many items (Add, Edit, Remove, Purge, Groups) for all Files sections, for example. And what's there to tell about 'Remove' anyway? You will probably end up with microsections that contain little to no information beyond what can be summarised as "Using the buttons on the right side you can add, edit and remove files from this list.", after explaining what the list is.

I guess my goal was to try and include as much detail about the user interface as possible. Agreed, having discussed the options, such as Add, Edit, Remove, Purge and Groups, once, there is no need to repeat it ad nauseam  .

I appreciate I didn't associate 'tasks' with most items, such as the one you mention. I included it simply for thoroughness. As I said in an earlier post, describing where, in the interface, someone may find a particular widget, that performs a specific task, may aid certain groups of users. I guess it's a question of how much detail id to much?

Panic wrote:

Just one idea to contemplate - IMHO the best manual I've ever seen came in three parts. Part I was for Mr. and Mrs. Average, and was written in the "see spot run" style. Part II was aimed at intermediate users who had a grasp of the overall concept and some of its implications and Part III was written for advanced users and was written appropriately.

This is an interesting idea, perhaps one we should develop further. I guess it all depends if it fits in with Melihs vision for this book.

[Melih]

so far all the ideas and direction is in the right way guys..
excellent start!

One small recommendation: Task orientiation... How can I do this or do that... thats what users are interested in. Novice users are interested about how they can do the basic stuff and so on..medium level guys, medium, advanced users more advanced stuff etc etc..the idea about having 3 levels of docs is an interesting one..

pls keep it going..

Melih

[xiuhcoatl]

I Think this is going good Although 3 Possibly and upgrade guide is alot more work?
Is anyone out there willing to put together a Upgrade guide.

This could be simple  I think you could just Post it in the "Help" forum
It should have some pointer on what folders and reg entries to remove. if the uninstall goes bad

I bet you could do it in 1-2 pages on a Word Doc although

Just out of curiosity has anyone tracked an install of 2.4 to see everthing it installs I want to on 3.0 when it is complete but have not had the chance/time with 2.4.

OD

so far all the ideas and direction is in the right way guys..
excellent start!

One small recommendation: Task orientiation... How can I do this or do that... thats what users are interested in. Novice users are interested about how they can do the basic stuff and so on..medium level guys, medium, advanced users more advanced stuff etc etc..the idea about having 3 levels of docs is an interesting one..

pls keep it going..

Melih

[kander]

I've been doodling with Google Docs for a bit the past few hours.. preliminary conclusion: Bad Idea - forgot I ever mentioned it.

While it does offer nice collaboration features, it sorely lacks in many points required for authoring a document somewhat decently.. fairly common stuff such as automatic T.O.C. generation, page headers and footers (page numbering?) and being able to style a single page (in fact the whole 'page' concept seems alien to Docs) are all missing.
----

Looks like the concensus so far is that the splitting out of user guides in three distinct documents is a Good Idea. That's good to see.

Opus Dei: No experience with upgrading 2.4->3.0 here - just did an uninstall+clean install. Did get into trouble upgrading 3.0 Beta3 -> Beta4, by reinstalling without rebooting in between, might want to warn users about that in an upgrade doc. Perhaps it's a good idea to split the upgrade doc discussion away from this thread though, to keep things focused?

[kander]

Here are some questions for Melih...

Just wondering - is there any chance that COMODO the company will be able to provide a collaboration Wiki for the Beginners Guide and possibly other documentation?

What's COMODO's position on the copyright issues I raised in the thread? Would the LGPL be a workable license for the document?

What would COMODO's preference be for the final file format in which the file would be produced (I'm guessing PDF) ?

Out of curiousity: Where and how will the beginners' guide be published once it is completed? Are we allowed to add our names in the documents on an 'Authors' page?

What kind of size are you hoping/aiming for? Book-format, or a couple-of-pages document?

--K

[Melih]

Here are some questions for Melih...

Just wondering - is there any chance that COMODO the company will be able to provide a collaboration Wiki for the Beginners Guide and possibly other documentation?

What's COMODO's position on the copyright issues I raised in the thread? Would the LGPL be a workable license for the document?

What would COMODO's preference be for the final file format in which the file would be produced (I'm guessing PDF) ?

Out of curiousity: Where and how will the beginners' guide be published once it is completed? Are we allowed to add our names in the documents on an 'Authors' page?

What kind of size are you hoping/aiming for? Book-format, or a couple-of-pages document?

--K

Wiki: you let me know what software you want, i will get it put on a server and make it available

LGPL is fine

PDF is fine

Of course you should put your names to that document. We would make it available on Comodo websites for the product as well as in the forums.

I think we want a sizeable document so that it will be the Comodo  Firewall Bible! (hmm.. bible..not for dummies.. hmm)

Bible for beginners
Bible for believers
Bible for Fanatics
hmmm..


thanks
Melih

[kander]

Thanks for getting back to these questions so quickly Glad to see everything being answered positively!

My personal preference for software is MediaWiki (the software powering Wikipedia and other Wikimedia sites) - but it's wise to see what others have to say regarding this.

[Melih]

Thanks for getting back to these questions so quickly Glad to see everything being answered positively!

My personal preference for software is MediaWiki (the software powering Wikipedia and other Wikimedia sites) - but it's wise to see what others have to say regarding this.

ok great. pls let me know when you have finalised the s/w
thanks
Melih

[Tags:]