h2g2 The Hitchhiker's Guide to the Galaxy: Earth Edition

Could we perhaps draw upon the experience of the Community as a whole and produce the ultimate beginner's guide to GuideML? I've come to realise that I'm very bad at explaining the basic concepts of GuideML simply because I'm so used to using it and other XML applications, and with the number of people who have great trouble figuring out GuideML for themselves... if we could get everyone who's ever learned it to contribute their wisdom, we could probably come up with something everybody can understand.

That sounds like a good idea, but i think we are likely to come up with something quite similar, and not much simpler to understand, to the <./>GuideML-Clinic</.>. What kind of thing did you have in mind? I think personal one-on-one (or 20-on-one, if recent threads are anything to go by ) help is the best bet.

Tango

I think what is needed is more of a tutorial covering everything. There are already severals beginners guides, but nothing which covers everything. The clinic is a good reference, but daughting when you first want to find out how to do things. I do think however that this is a bit large for a Talking point. More of a collaborative uni project or something to liven up the CWW?

spelugx -- getting

Maybe a step by step tutorial would work, although i'm not sure. Not everyone needs to learn GuideML in the same order, a lot of things aren't learnt by all. For example, how many people know how to use the tag and it's brothers? TABLEs aren't very common, lists aren't important straight away. What level would you target?

Tango

I like the idea of a tutorial. Perhaps we need a few for Researchers at different stages. The most important one would be for the absolute beginner... after that it should be reasonably straightforward to work out what to do.

I wonder whether this is the sort of thing that could be collaborative, but put together by a few specialists rather than the whole Community. It would also be important that it was thoroughly 'tested' - Peer Review would be the most logical place, but I'm not sure how many newbies hang out there

Anna

If it's going to be a joint project, rather than a collaborative one, count me in!

~

Although it's not quite a guide to GuideML, Titania's "Spicing Up Your User Page" is very good and written for the beginner.

A690518

Indeed it is, but I can't help feeling that we're missing the definitive guide to GuideML for beginners... and as I said, I'm useless at writing things like that. I'd tend to start with some of the concepts behind XML, the aims and objectives of it, and the nitty-gritty of the syntax before I even started on what all the tags were - and while this may teach people GuideML, I doubt many people would read past the first paragraph.

That the best way to teach someone who already knows about other languages, more than complete beginners.

Tango

After reading another thread, I started trying to put a project exactly like this together.

The other thread was F19585?thread=252916 and the index page A985773.

RhoMuNuQ

To the italics: Could we structure this like a university project, but instead of the finished project becoming a set of 'edited' entries, it becomes 'help pages' instead? Is this technically possible?

Is it better to leave this in the community so that it can develop with time? The FAQ could benefit from this for example

spelugx.

That sounds like a good idea, a uni help project... Yeah, i like that.

Tango

This is just what we needed. Someone (maybe me) should get in touch with Shazz or Greebo and have this put as an announcement in the next Post so we can get more people involved.

I love it when a plan comes together

A university help project sounds like a great idea. Yes, the entries could become help pages, no problem. I'd still like the entries to be user tested though, so putting them through a review forum of some sort would be good (we're tending to do that with new or rewritten help pages, these days, anyway).

I've rewritten a couple of the help pages recently and tried to keep the instructions as simple as possible and the length of the text very short. See <./>welcome</.> and <./>writing-guidelines</.>



Anna

MaW - That's a great idea! I created a thread on the Gurus homepage asking if any Gurus would like to help, but I didn't think of putting an announcement in the post. If you could sort that out, that would be brilliant.

Anna - Are the current half-written pages in a suitable style? They're all linked to from A985773. Once all the pages are written, would the Collaborative Writing Workshop or Peer Review be the preferred review forum?

RhoMuNuQ

I'll get in touch with Shazz and get the announcement in for Thursday's Post

That's great - thanks!

RhoMuNuQ

'tis done!

Dear RhoMuNuQ,

The pages are looking good so far Probably best to Put them in Peer Review with a note attached saying that they're destined for a University Project

Anna

MaW:

Anna: Thanks - I know that just now the pages are only first drafts. I'll try my best to have the project ready for PR within four weeks...

RhoMuNuQ