Ok, Then, let's step back and look at this......
If you look at my last letter, I have provided some insight: lowest common factor on ability, screenshots, etc. Table of Contents, Glossary, Cross-references, external references, templating.... I believe these to be pretty standard solutions to documentation issues.... Why would someone like me have problems with installation with the documentation given? Let's start by looking at the Configuration and Installation Guide: (First off, you may want something like WordPress to be installed to perform content management and use it as you web site system) Nice Intro. Contents uses hyperlinks - very good.... About this Guide. No biggie there. However, I understand Funambol is a big win for it, however, 'horse before the cart' Define Funambol's functionality and why it's such a big win (aka What does it do? What does it give you?) Introduction - I will address just the first two paragraphs....... It introduces Sogo and what it does.... kind of.... Again, 'horse' issue. Define everything you're talking about please. This includes: through your favourite Web browser and by using a native client such as Mozilla Thunderbird and Lightning - List favourite web browser examples known to work. If it's a Microsoft shop looking to migrate, does IE work with it? Have you tested it? Which versions? This applies to all other browsers.... Opera, Safari, Konqeror, etc, etc, what versions are known to work. Where is the document's 'known issues' and the subsection on 'browser compatibility'? SOGo is standard-compliant. - This may mean little to some persons but it is definitely useful to those 'in the know'. Also, due to MS' lack of standards compliance, you are going to have to constantly, throughout your document, have screen shots of things like 'Outlook' clients connecting and working just fine. It supports CalDAV, CardDAV, GroupDAV, iMIP and iTIP - This requires translation. It's sad but true. Wikipedia reference links or you can copy the definitions and put them in a glossary and hyperlink them there. Otherwise, you've got low-end people turned off. Sure, some people just want to muddle through a 'quick start', but there are trained minds out there that need an argument to go to their biz bosses and say "It's all standards compliant. We won't ever have vendor lock-in again. It handles the standards for calendar, contacts, groups and others so that we can migrate in the future if we need." reuses existing IMAP, SMTP and database servers - Same issue here. Also, again, give some examples that are known to work for each protocol and the LDAs and MTAs that are known to work. (Also, define LDA and MTA :-) ) Define IMAP, SMTP, LDA, MTA and put them in the glossary and hyperlink to their definitions. Next, list the MTAs known to work and their versions..... Postfix v 2.0, Sendmail 9.0, EXIM x.x.x. LDAs - Dovecot 2.x.... (To start your list, I'm on FreeBSD 9.1, Postfix 2.10.0.1, Dovecot 2.1.15... :-) ) Database servers? Why do I need a database server? Explain it before you get here..... Let them know somewhere above that the calendar information, contacts and other things are stored in a database. Now, which databases? Can I use MS-SQL? Which versions? I may be wanting to get away from the slowly fading MS world and it's licensing costs. If not, let them know it's "untested". I'm using PostrgreSQL 9.2 and it's working flawlessly. So, there's one DB and version to start the list. :-) Who is using MySQL? What versions? BTW, it is acceptable that once you have compliance, as long as you continue to test, you can say something like: FireFox 9.0+ instead of listing every version. making the solution easy to deploy and interoperable with many application No, never make a statement like this. In the back of some people's mind, they may be undertaking something enormous for them. Let them know there is the incredible help of this community to make SOGo be the best player in the market. A statement like "Although we at SOGo have made every effort for compliance, ease of installation and integration with existing infrastructures, we recognize there may be an unforeseen issue. We want to hear from you if you encounter any problems so they can be addressed and corrected in a future release. Please read through the guide carefully and note anything that is not obvious and let us know. SOGo wants to be the best and we recognize through constant feedback from it's users on features and 'ease of use' can we get there. If you have difficuly, please sign up for the forums at.... by doing..... Ok, ladies and gentlemen, is this clear enough? I cannot go through the entire document right now, however, I would suggest you create threads in your forums for an install for each OS and the primary variants...... Take a poll and go for the top three of everything people are using with: MTA LDA DB Also, take more polls of your community for "known working" browsers, OS, other collaboration clients, etc... I believe your install document will probably grow to a full 200-300 pages quickly and there will be nice little sections like: Installation with Dovecot: (with subsections of various OS dependencies and MTAs) and things that will need to be changed in the sogo.conf file and the apache file (BTW, good job with the apache stuff.... it just took me a second to realize that it goes in the /usr/local/etc/apache22/extras directory on FreeBSD and that needs to be enabled in the /usr/local/etc/apache22/httpd.conf file near the bottom of the file..... Oh... and all the paths in that file need to be changed to reflect the installation of SOGo) (Whoops, while writing the above, I forgot about web servers.... it works with Apache 2.2 :-) ) So, I hope this was helpful. I really like your product thus far... however, it was a lot of time spent deciphering and querying the forums.... I still haven't tested 100% but everything seems to be working quite well. P. ________________________________ From: Ludovic Marcotte <[email protected]> To: [email protected] Sent: Saturday, July 6, 2013 4:41 PM Subject: Re: [SOGo] Dear progammers and architects On 2013-07-06 4:27 PM, Paul Pathiakis wrote: > The rest of the people will just throw their hands up in frustration > and walk away. Is that what you want? As I said in my previous email: "If you have ideas on how to improve the doc, share them." So far, you honestly haven't shared anything but rants in your two emails. I'm not defensive at all, we all want to improve SOGo but that starts with concrete things. So again, if you have ideas on how to improve the docs, share them, it can't be more simple. -- Ludovic Marcotte [email protected] :: +1.514.755.3630 :: http://inverse.ca Inverse inc. :: Leaders behind SOGo (http://sogo.nu) and PacketFence (http://packetfence.org) -- [email protected] https://inverse.ca/sogo/lists-- [email protected] https://inverse.ca/sogo/lists
