What documentation do we already have? (DocBook = Great, huh?)

[Szandor]

I've been checking out DocBook and with a lot of products having good support for it I think it's the best option for all our documentation needs. It's free, simple to use and since it's SGML/XML it's completely text-based and future proof. Through XSLT we can easily convert it to other formats and we could even add layout through CSS and use it as it is in the help system. I'll be sure to convert the documentation for my syntax proposal.

This brings me to the actual question - how much documentation do we have for EE at the moment? Apart from "I want this feature", is there anything written yet?

[Pvt_Ryan]

tbph i dont think "anything" has been done for EE bar deciding on its name...

I cant believe i am going to say the following but...
A wiki would be good (providing access was limited) to get a list in a comprehensive form of Core features, plugin features, default behaviour. etc

I normally dont recommend wikis but they are excellent at consolatating information that tends to get lost in threads..

With the wiki we could basically list all our requirements and outline things.

I just dont believe that a forum is suited to this sort of task, and i think that is 1/2 the problem. Forums/mailing lists are excellent for discussing a problem or feature but shite at documentating it, Wiki's are shite at discussions but great for storing/documenting information.

A good eg is if you google for a linux problem you will end up reading a 30page mail archive or forum thread and the answer you want is hidden at about page 27. While it does make for an intereting read very few of us care about other peoples trial and error we just want the solution.
On the other hand if someone had copied the solution and created a wiki with some decent search algorithims then you could have found the solution without hassle.

If we were to get a wiki we could have a section called documentation which would state:
Documentation will be done with docbook.
<How to use docbook for documentating EE>
/end

just an idea..

[pn8830]

I can't recall anything other then your SDD doc which was pretty comprehensive. From the other hand there is not much to document, unless there is something working.
Cheers,
PN.

[Arantor]

Since EE is, at best, vapourware, all we have is the functional SDD documentation.

For CE, on the other hand, we have the original CE manual, plus its original design spec, and lots of miscellaneous bits and pieces.

I agree DocBook is probably the best answer overall; I haven't gotten round to getting my hands properly dirty with it yet, I just haven't had time.

On the subject of a Wiki, it's doable, however I think I'd want separate CE & EE wikis if we went down that route. If this is something people will think is beneficial and practical, I can roll out a wiki implementation (typically MediaWiki unless anyone has any burning issues with that? - only problem is that for now I'm limited to 1.6.10 due to not having PHP5 on the server yet, and some of the stuff on the server has not been upgraded to run cleanly on PHP5)

[Pvt_Ryan]

Since EE is, at best, vapourware, all we have is the functional SDD documentation.

For CE, on the other hand, we have the original CE manual, plus its original design spec, and lots of miscellaneous bits and pieces.

I agree DocBook is probably the best answer overall; I haven't gotten round to getting my hands properly dirty with it yet, I just haven't had time.

On the subject of a Wiki, it's doable, however I think I'd want separate CE & EE wikis if we went down that route. If this is something people will think is beneficial and practical, I can roll out a wiki implementation (typically MediaWiki unless anyone has any burning issues with that? - only problem is that for now I'm limited to 1.6.10 due to not having PHP5 on the server yet, and some of the stuff on the server has not been upgraded to run cleanly on PHP5)

I just think that the wiki may help us get some progress on EE at least as it would so people where it stands.

You could run php 4 as a apache module and php 5 as a cgi binary until you are ready to switch to php 5 completly.

But if its too much hassle then leave it until your server is ready.

The guys doing it need to either make some "visible" progress or step down and let someone else take up the job..

[Szandor]

I'm sceptical about wikis for programs myself. I agree that it might be a decent tool for internal documentation purposes, but doesn't it seem kinda like overkill with a wiki for one program? Also, the wiki concept of the public editing the articles may be all well in some cases, but for documentation it's not really that good of an idea I think.

Still, if that feature can be turned off I have nothing real against using a wiki. A CMS would be the only good alternative I guess (I have used CMSMS myself a couple of times and I like it very much), but the internal linkability of a wiki is quite nice.

What I'm saying is basically: Yes, a wiki (or CMS) for internal gathering of info would be great to have.

[rageboy]

I'd be happy with a wiki. Works well at http://developer.pidgin.im