Hi, this is my first post, i've been reading the forum for a long time and it's a great forum, atm i didn't need ask something that other people doesn't ask before.

Recently, i found the SlimDX library, this a amazingly and a greatly tool, the documentation page it's so complete but, i have one recomendation.

At slimdx's documentation page, you can download a compiled chm for documenting yourself offline, this is an obsolete system, now microsoft recomends use MAML. And this no only for stay updated, but on Windows Vista or Win7 you'll have many problems to read the .chm because it's a "security risk" file.

In conclusion, I'd like to know if it'd be possible to change from CHM to MAML, and make this tool more perfect and efficient.

Thx for read me :)

Quote:Original post by Mike.Popoloski
MAML is just a help authoring language, not a complete package. We use MAML to author our content and then compile it into a CHM for distribution. I'm not sure what you'd rather we do; the only other help solution I know about is integration with the Visual Studio helper viewer (help 2.x), but that's not something we find all that useful.

Mmm, i know what are you refering, i think that documentation isn't a trivial question, but i'll try to help if i can :)

There are some solutions for this problem, of course one of them is allowing the integration on Visual Studio (ok, not all the people use Visual, but a lot of use it), the problem of this is simply = you need to update 2 or more outputs.

I think that one of the best solutions is, allowing people to use his browser (Internet Explorer, Firefox,...). One browser has many benefits over CHM, first of all, you can open at the same time many pages (usually when i search information in the MSDN i have many pages), this is useful because you can search related documentation without remember the last search.

With a web page, you only need to update your XML help and you have the webpage updated, and if a user wants a local copy, he can download the webpage. Your actual web page, with JS, can not be downloaded.

You can have a local copy, like the CHM, and you can work without Internet connection, and personaly i have this situation usually. At this part, there aren't improvements against CHM.

Apart, you can update the web documentation page to allow new functions, meaby, like send our own descriptions about SlimDX functions, or Example code. Yes, i know that we can update the documentation localy and modify the libraries, but i think if all the work is centraliced, SlimDX could be improved more quickly and in more directions. With CHM this cannot be possible.

On the other hand, you should make all the web construction, but SlimDX is a really powerfull tool, and it have a lot of work on it, i think it might be expanded. Be sure, that my only intention it's try to help with new/old ideas.

I hope this helps, thanks for reading me.
Regards.

Quote:
Apart, you can update the web documentation page to allow new functions, meaby, like send our own descriptions about SlimDX functions, or Example code. Yes, i know that we can update the documentation localy and modify the libraries, but i think if all the work is centraliced, SlimDX could be improved more quickly and in more directions. With CHM this cannot be possible.

I don't understand what you're getting at. We have a single source from which we generate our documentation. We can modify that source and use various tools, as appropriate, to convert that documentation into various output formats we consider useful -- one of them is the website, one of them is a CHM file for offline viewing. We don't update the CHM and website documentation separately, it's all centralized in one source format. Which is exactly what you seem to be suggesting.

On you documentation, there are so many functions with no information. You dont describe this function of one procedure or their common usage, or what is each parameter.

With you actual (and static) system of documentation deployment, the only way to add more information about the code is changing my local copy of your source code, recompile it and generate a new MAML - CHM

Because of this, the people who wants help you by improvements, examples or more explanations about the functions and parameters, can't do it.

I'm purposing change the actual system of online-offline documentation, and make a only one system => one web page, thats allow search code online and send our examples online, and the posibility of have a local copy of this page and allow the seach of code offline.

This is a similar system of JAVA, when you want to seach information via online, do you have a webpage with so many functions for popular participating. But you can download a copy of the page, and have your own local copy offline, for seach when you can't stay connected.
http://www.oracle.com/technetwork/java/javase/downloads/index.html

There you can see the example, you can download a zip with the documentation page or you can use the online page. With this system, when you want to add new posibilities to your system, either the online and offline modes, have the same benefits.

I hope now i explain it more correctly.
Thx for your attention.

Quote:
Because of this, the people who wants help you by improvements, examples or more explanations about the functions and parameters, can't do it.

First of all, nobody wants to do that -- we receive code patches all the time on our issue tracker. We have never, to my knowledge, received a documentation patch.

Second, your proposal is essentially adding a community-controlled wiki to the documentation, much in the way the PHP manual works. That has several disadvantages:

For one, it's only available online and thus people with limited internet connections would have trouble accessing it. They wouldn't be able to make use of the contribution functionality, either.

Second, it's a wiki, so it's very difficult for us to control and vet the quality of the content that goes on there. Bad documentation is better than none, and it would be very easy to get bad documentation out of wiki.

Third, it would make our build process vastly more complex because we'd have to go to great measures to maintain the existing user contributions across every build we make or otherwise reintegrate them back into our source build.

Finally, it would require significant web-related engineering on our part, and we don't believe the benefits would be worth the time we'd have to sink into it.

Documentation is very difficult to get right; we know our documentation could be improved in a lot of ways -- but it is sufficient for now, especially since we link to the MSDN documentation for the equivalent native functions when possible. In short, we are unlikely to ever implement this idea.

As i sayed before, documentation isn't a trivial question. You have your method and your whys, thx for explain it to me so well.

I agree with you, that bad documentation is better than none, you don't have a bad documentation, i only thought that it could be better, but with your reasons and whys, i think that you'll complicate all innecesarely.

Thx again for your attettion.
Have a nice day :)