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 [email protected] ++

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 "[email protected]" mailing list so at least corrections can be sent somewhere that gets a response?

Reactions and feedback wanted if you have on ;-)

pedro