Emerald Editor Discussion
May 27, 2017, 08:23:30 pm *
Welcome, Guest. Please login or register.
Did you miss your activation email?

Login with username, password and session length
News:
 
   Home   Help Search Login Register  
Pages: [1]
  Print  
Author Topic: What documentation do we already have? (DocBook = Great, huh?)  (Read 41477 times)
0 Members and 1 Guest are viewing this topic.
Szandor
Senior Miner
***
Posts: 92



« on: July 25, 2007, 10:49:59 am »

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?
Logged

"Cleverly disguised as an original signature..."
Pvt_Ryan
Master Jeweller
******
Posts: 422



WWW
« Reply #1 on: July 25, 2007, 11:33:23 am »

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..
« Last Edit: July 25, 2007, 11:35:56 am by Pvt_Ryan » Logged
pn8830
Global Moderator
Jeweller
*****
Posts: 252



« Reply #2 on: July 25, 2007, 02:25:31 pm »

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.
Logged

Entities should not be multiplied beyond necessity
Arantor
Site Administrator
Administrator
Master Jeweller
*****
Posts: 618



« Reply #3 on: July 25, 2007, 07:17:22 pm »

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)
Logged

"Cleverly disguised as a responsible adult!"
Pvt_Ryan
Master Jeweller
******
Posts: 422



WWW
« Reply #4 on: July 25, 2007, 07:30:17 pm »

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..

Logged
Szandor
Senior Miner
***
Posts: 92



« Reply #5 on: July 26, 2007, 04:07:51 pm »

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.
Logged

"Cleverly disguised as an original signature..."
rageboy
Jeweller
*****
Posts: 305

Ankit Singla


« Reply #6 on: August 10, 2007, 12:14:56 am »

I'd be happy with a wiki. Works well at http://developer.pidgin.im Smiley
Logged
gkaniase
Prospector
*
Posts: 2


« Reply #7 on: August 22, 2012, 10:01:01 am »

Hello everybody, I want to write a System Requirements Specification (SRS) for this project if the administrators wants it.
Logged
pn8830
Global Moderator
Jeweller
*****
Posts: 252



« Reply #8 on: October 08, 2012, 05:48:01 pm »

Go ahead. Feel free to post here.
Logged

Entities should not be multiplied beyond necessity
Pages: [1]
  Print  
 
Jump to:  

Powered by MySQL Powered by PHP Powered by SMF 1.1.19 | SMF © 2013, Simple Machines Valid XHTML 1.0! Valid CSS!
Page created in 0.162 seconds with 18 queries.