Hello Alex, Simon, Max, Georg,
I understand you, and I completely agree that a written manual for each process would be great. However, writing such a manual is just impossible now. Remember that I am the "one-man band" guy (great historic James Taylor album by the way
).
To write such a monumental work, I'd have to stop development completely, stop all video tutorials and all processing examples, and concentrate during many months on the hard task of documenting every process and every parameter. Of course, this would include screen shots and practical examples to demonstrate what each parameter does and why; a text-only manual would be useless. Take into account that I also have to provide email and forum support on a daily basis, along with bug fixes, which are time-consuming tasks.
If I'd stop active development, PixInsight would be a dead project very soon. This is an extremely competing micro-world, and there are quite a few guys out there that would be extremely happy to see PixInsight in the cemetery of failed software projects. If just to annoy them a little, I'll keep them from getting what they want
And guess what? After all of that work, many users wouldn't read a word. An example is PixInsight LE's documentation. It took me five months to write it (from May to September 2004, if I remember well), and I just documented most parts of the user interface, and just the most important processes. It's true that in 2009 I have more resources and much more experience, but this gives you an idea of what we're talking about. Even today, most PixInsight LE users don't read the documentation at all (I sometimes read things on some forums that make me laugh or cry, depending on my mood
).
Regarding documentation and learning material, this is my current plan in priority order:
1. Video tutorials. I think this is the best tool we have to teach our users. This is my highest priority at this moment. Besides the fact that a video shows lots of things that just cannot be described with written words, I can produce video tutorials, even extremely complex ones, in a fraction of the time required to write a tutorial or a processing example (thanks to Alex (the Mac voice), of course
).
2. Written processing examples. In my opinion, written processing examples are much more useful than a per-process documentation to communicate how the different tools work and their practical usage. A written example is much less expressive than a video tutorial, but it can show more "detail", so to say.
(Aside: An example (video or written) has a great advantage over a per-process manual: it shows how the different tools can interact through a real step-by-step processing example. Many tools really don't make any sense but if used in the context of a specific workflow. For example, you cannot explain HDRWT well without stretching the image. You cannot explain noise reduction well without wavelets, etc.)
3. Written tutorials on specific tools. There are tools and processes that require written documentation. An example is PixelMath. This tool needs a reference manual, just as a programming language does. The whole scripting system also falls into this category.
4. User interface documentation. The GUI requires some written documentation. For example, a list of keyboard shortcuts on all platforms, and a list of mouse actions. An overall introduction would also be desirable. Other than these, I think the GUI can be much better described by means of video tutorials, instead of (boring?) written descriptions.
