The Getting Started Guide - Go for a split ?

Engines, Libraries and Tools Xith3D Forums
#1

Okay, I see only advantages here :

  • HOWTOs are automatically listed on the page at xith.org
  • Anyone with the “Writer” status on xith.org can write one
  • We have a wysiwyg HTML editor integrated into Joomla (finished are the bad LaTeX days…)
  • We can still convert them to PDF if needed (there’s a little icon to activate in Joomla!)
  • We have a search function on the site that will search also on HOWTOs

Oh, just one con : Somebody has to do that… I could, but I don’t guarantee any deadline.

#2

Ultimately it’s up to whoever is writing them I guess :slight_smile:

I don’t see much point changing the format of current GSG sections, except perhaps those that are out of date / constantly changing. I think you’re effort is probably better spent adding new material than converting old ones.

I personally really like LaTeX, it produces very professional looking documents, but I can understand the reasons for adding new material as HOWTOs.

Cheers,

Will.

#3

Well for me it’s not too much work to convert, and I think it’s really overhead to have to do the LaTeX compilation, and uploading to the FTP and so on. With Joomla, it’s a click away…
And PDF documents produced by Joomla are not so bad-looking… but the layout isn’t really respected.

#4

if it’s not too much work - ok… we could still keep the getting started guide (to have all in one pdf is a good thing) …mmh that’ll leave us with keeping the Getting started up to date or at least having the information in it not going wrong…

#5

Mmh yeah but I maintain having two formats of documentation isn’t a good thing.
On the other hand, having only one PDF file is cool.

#6

With the GSG it’s essentially a book and you can (and I have) printed it as one. It’s a little thin now, but that could change. Plus there’s the HTML version for web browsing. I was always quite happy with its presentation.

That was the old way and I think it worked quite well at t he time. If you think using the joomla would encourage the development of more articles (and that these articles and the GSG don’t really co-exist well), then it sounds like joomla is the way to go.

By the way, the link on page http://www.xith.org/pages/getting_started_guide_demos.html to the GSG seems to be mangled.

Cheers,

Will.

#7

I agree it’s a difficult choice to do.
So here’s what I suggest :
Keep the GSG & the HOWTOs, BUT

  • Make the GSG course-oriented, say you learn all in a continuous, logic way, but it isn’t really convenient for quick search of one particular point. It helps to introduce you to Xith, and to improve your knowledge on approximately all domains.
  • Make the HOWTOs feature-oriented. These can be compared to a FAQ, but they are truly articles, an define a more or less detailed step-by-step recipe to do something with Xith

Fixed. But I thought I had give you the rights to edit pages, Will ? You just need to login and then you have a little icon with a paper and a pen, which when you click on it starts an editor and you can edit & save the page. It took me ~20s to fix this page ^^

#8

The GSG was intended to be a consistent step-by-step guide such that you can read it like a book. The idea is that new users should have something to start with.

If it helps the GSG in some way you can change the format, but I think it is more important to update its contents and add new sections. The GSG can easily be modified via CVS and Will and I have written a nice ant build file,so if you have LaTeX installed I would just advise you to go ahead. (I guess you can commit new stuff even without having LaTeX, if you just drop someone a note who can compile a new version.) Unfortunately I don’t use Xith3D anymore (and haven’t used it for a long time), which is probably a reason why the GSG is not in a good state.

#9

OK, I see. So when I’ve time I improve the GSG. and suggest the HOWTOs are just 5-lines “Tips” with just a description of what effect is wanted and how to achieve it in a few lines of code.