• entries
422
1540
• views
490627

# Complication in the FAQ

102 views

Been spending more time working on the forum FAQ, but I've realised a slightly complication [headshake].

Currently we have "native" and "managed" DirectX9 programmers frequenting the forums. Soon we'll have D3D10 stuff, probably also some XNA Framework stuff as well...

Which means that even listing function/enum/parameter names gets complicated. My constant references to the C/C++ API might not be of any use to a pure MDX programmer. Sure, there are many similarities, but its not always obvious - especially when this FAQ is of most interest to those who aren't experienced.

So I've been thinking about "tagging" code fragments with [C/C++, Direct3D9] or [C#, MDX 1.1] etc...

But if I also want to cover the next generation I'd quickly end up with 3-4 versions of EVERY code fragment. This chews up a lot of space - particularly when most people are only interest in 1 of the options.

It also starts to apply to individual FAQ entries - do I need to start tagging those with version/API numbers...

Why can't people just make my life easier and use a Real Programmer(TM)'s language??? And no, I don't mean .NET [razz]

Seriously though... anyone got any thoughts on how to effectively combine multi-API/language content?

Jack

That's a hard one Mr.Hoxley [headshake]
I don't know if these are any good advice at all, since I don't know what technical limitations you have and exactly what kind of information will be present in the FAQ.
But if it's possible to make the FAQ content dynamic, then this idea might work.
Instead of hard writing all content, you could fetch content for each segment based on selected API/lang. So for example, "How do I use ID3DXSprite?" for C++/D3D9, becomes "How do I use Sprite?" if C#/D3D9 is selected, and "How do I use <put D3D10 equiv. here>" for D3D10.
Then inside that segment the content might be the same or similar for C++/C#, so could fetch the same content. That content however might have keywords which are once again variables, so "ID3DXSprite::Begin()" for C++ becomes "Sprite.Begin" for C# etc.
All functions, classes, enums etc could be variable instead of static text.

You could have some kind of API/lang selection at the top of the FAQ, or above every affected segment, so that you can switch the content by a single click. That would probably be quite convenient for the user. It does not however solve the problem of having to write all the extra content.

A parallel idea might be to have some standard pseudo code which you use for all code segments, so that everyone can understand them. Then you could have api/lang specific code to accompany that, but not guarantee that it will be available for all languages and/or API:s.
In this way you can fill in missing API/lang specific code a little bit at a time whilst still providing, what hopefully will be, comprehendible pseudo code.

Anyway, I don't know if this is any help at all, I didn't really think it through that thoroughly [smile]

Hope you come up with a good solution

EDIT: typo
Regards,
Omid


Thanks for the comments/suggestions - appreciated [smile]

Quote:
 I don't know what technical limitations you have and exactly what kind of information will be present in the FAQ.
I'll double-check, but I'm pretty sure its rendered/formatted in the same way as a regular forum post.

Which, unless I'm missing something probably rules out much of your idea [headshake]

I did think of something similar - like how MSDN (or at least the offline MSDN library) has a language filter menu so you can show/hide fragments in particular languages.

As you pointed out - however it eventually gets presented I'll still have to write the content. So for now its not important, I can just have a very lengthy draft that I can just reformat as/when necessary.

Cheers,
Jack

I can think of two options:

1) Do it in the API of your choice and tell everyone else to figure it out from there.
2) 'hire' some 'translators' who can convert the code from API I to API II, and in the main forum faq, have links to variations of the FAQ with the relevant code, e.g.:

Quote:
 Welcome to the DirectX forum FAQ. This version contains just C++ code for Direct3D9. For MDX code, click here

maybe we should just poke the powers that be to allow the kinda scripting required to make bits vanish and appear and such like?

I mean, I can see why regular posts aren't allowed scripting but you'd have thought being mods they would trust us a little more... [grin]

Quote:
 Do it in the API of your choice and tell everyone else to figure it out from there.
[lol] Yeah, that'd be a nice option... but it does seem that there are MANY more MDX threads these days, and they only seem to be increasing.

Quote:
 'hire' some 'translators' who can convert the code from API I to API II
I'm currently looking into this - at the very least a bit of proof reading for the MDX parts I dont know about...

Quote:
 you'd have thought being mods they would trust us a little more...
I'm gonna embed goatse into the forum FAQ [evil]

Cheers,
Jack

## Create an account

Register a new account