#1  
Old 12th November 2007, 07:29
pedro_morgan pedro_morgan is offline
Junior Member
 
Join Date: Aug 2007
Posts: 22
Thanks: 2
Thanked 3 Times in 1 Post
Default Documention thoughts

I only got inovlved recently with ISPConfig as its running my online server (Plesk replaced), saw some holes in the docs, contacted the dev and as an experimental documentation branch is already established, thanks to till and all.

http://docs.ispconfig.org/en-sandbox-dynamic-site/

So if I may express some of my thoughts and opinions for everyones digestion as v3 is looming on the horizon ;-)

I would enjoy taking on some of some the documentation maintanance stuff, as I do currently with Smarty amongst other FOSS projects. However, I do also see that most of the developers are German and the code variables are foriegn.. as an english speaking welshman is mothertall.

My vision would be to have a complete set of chapters for example (in no ordinal order at the moment) and this lot please add 2++

===ISPCONFIG 3===
* Introduction of what it does and how its used
* Prerequsities and Expectations of the installation and various platforms
** Services
*** Web (apache)
*** Auth ssh etc
*** Email
*** DNS
* Adminstratiors Install Guide
** The target Machine
*** Debian, Ubuntu, SUSE etc
*** Deployment scenarious
* Appendix ++++
* Please send more to docs@ispconfig.org ++

Yes! we are maybe talking about a book, with lots of chapters by various, like svn manual/book ;-)

From my experience smarty.php.net uses <docbook> and cvs(glues back the ripped out hair of frustration), which is not easy to maintain by any stretch of ones imagination, so HTML is confirmed by till as the "standard" for the docs; so we can at least all hack and edit it one way or another. Only future issue here is translation but I think we can do that as we go along imho. Firstly we need a clear "structure" and purpose.

So to do this what I propose and is the issue for us to mentally chew on is how the documentation is delivered.

And I think that this can be delivered by having a "slightly" dynamic website with "user comments/annotation" that can be "merged" into the "official docs".

The "dynamic" site can then be "spooled/ripped/lifted" into static html documents (WWTIWUG> "What Was There Is What U Got").

I dont think the documention need to exist in ANY other form (>> eg pdf is a waste of time (unless we do a book .. more later! == $ (oops Euros)).

By "dynamic" I intend to parse "parts" of log files etc and embed them as the original "pure.txt" files embedded within the docs (maybe with Geshi).

This also means cut and paste config files which is valuable imho as a newbie approaching the ISPonfig "system".

=============== =============
Big Word >> CONSOLIDATION <<
=============== =============

At present most of the doumentation and "help" (panic its gone WRONG!!!) which is the only time we all really want documentation is a bit misleading in critical areas; even in the forums a search for a small "issue eg foo" yields a lot of "spurious" results that are not applicable.

I propose to shorcut and circumvent "an issue" by taking a forum thread on "issue" and redirect that question to the chapter and FAQ in the official documentation. If that is possible??

Once issue is resiolved then is in official docs. and like woise points back the other way .

I would also like the documents to be signed off, ie the sequence of events as documented is exactly what happens and verified, AND the docs must be updated to reflect that as systems are updated for example. eg python or php versions?

Generating ISPConfig "code" documentation from "autogenerated" class objects in various computated languages and "diving" into the code is something that does need considering in the official docs initially.

Having a "confident initial documentaion" will make systems administrators happy and is the first step to completness and perfection of what ISPConfig will be in the future as stuff changes around us. Coders are welcomed to read the source later as the system develops.

What I would like immediatelly is
* install logs
* update logs
* exampel config files for various platforms
* Recurruring question the forums and resolution > ie faq and I think that may need to be slightly platform specific.

Do we need a page for each "application" eg apache/php/proftp/clam/et/all ??

These are some of the thoughts goin through my little mind...

I could write more but for now I gonna review and update the svn/docs (after groklaw.net) as I think this is a cool project and am./want/is part of the success of IT;-)

Also if possible can we create a "docs@ispconfig.org" mailing list so at least corrections can be sent somewhere that gets a response?

Reactions and feedback wanted if you have on ;-)

pedro
Reply With Quote
Sponsored Links
  #2  
Old 15th November 2007, 11:12
till till is online now
Super Moderator
 
Join Date: Apr 2005
Location: Lüneburg, Germany
Posts: 35,981
Thanks: 825
Thanked 5,371 Times in 4,218 Posts
 
Default

I think the documentation sandbox looks really great and we shall continue this way.

I'am not sure if we shall make chapters for every application like dns, postfix etc with the configuration as everything is already covered in the perfect setup guides and there can be no "general" configuration as it differs for every linux distribution and version. We would end up in having the same like the perfect setup guides, only grouped by application and not by linux distribution.
__________________
Till Brehm
--
Get ISPConfig support and the ISPConfig 3 manual from ispconfig.org.
Reply With Quote
Reply

Bookmarks

Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump

Similar Threads
Thread Thread Starter Forum Replies Last Post
CBand Help sf004 HOWTO-Related Questions 5 26th June 2007 23:15
ISPConfig Best Practices - Your thoughts. daadams2000 General 4 12th March 2007 19:48


All times are GMT +2. The time now is 14:17.


Powered by vBulletin® Version 3.8.7
Copyright ©2000 - 2014, vBulletin Solutions, Inc.