PixInsight Documentation

[Jack Harvey]

Reflecting on the poll we took about needs and some of the recent postings on other sites, documentation is a number one issue.  Here is my proposal, which I have not run by anyone so would need the blessings and work of several people.  I think a good bit of the documentation issue could be solved by enhancing RBA's "Unofficial" guide http://blog.deepskycolors.com/PixInsight/ and making it official and easily accessed from the PI help file, if not from the individual tools themselves.  ie you are using DBE and it is not working like you like, you click the "H" on the tool task bar and it takes you to the part of the guide on DBE.

Added to the guide as it is will need to be a small paragraph on BASICALLY how to use the tool.  Also hyperlinks to any existing videos.  Now you have ALL the documentation in one place!  For example added to the section under Noise Reduction/ GreyCstoration:

User Tip:  This is a powerful noise reduction tool to be used in the last few steps of image processing.  It is processor intensive so recommend using Preview Windows while selecting the adjustments.  Also recommend using a luminance mask to protect areas of high signal.  The defaults are not appropriate for most images and the sharpening needs to be 50% or less, and both the amplitude and noise scale need to be set around 15 +/- 5-10 depending on your Preview results.  
Video click here
Wiki click here

ALso should have sections on Using Icons, Using Previews, etc.  And a final section going through a SIMPLE processing workflow for a RGB from Masters to finish

[sreilly]

This is similar to what I had asked Rogelio yesterday. I was wondering if Juan had approached Rogelio about using his "Unofficial Guide" as a basis for documentation and edit and add as needed. My belief is that this would at least quite the complaint about lack of official documentation, meet the needs of those of us who feel we could benefit a great deal from it, and possible help drive sales as a result.

[RBA]

Juan was aware I was writing that document and in fact he answered several questions while I was working on it. Yes, the document needs some "official" work, but it'll be a starting point to the documentation system Juan is working on.

Complaints about PI not having an "official" documentation are getting boring - fact is, many people who fail to be productive with PI blame it on the docs when the reason is more because they're jumping on the software with a PS mentality or maybe because they think they can master the software in three runs or with little effort (as if they learned everything they know about PS in three runs also). It's been a while I put deaf ears on that kind of complaints (you can read them a mile away). But I have to agree the software is mature enough to come with some documentation/help system and some complains don't come from "smarties" but from people who simply feel they could get better acquainted with the software and the workflow if they had a guide right at their fingertips (whether that turns to be the truth is another story). Regardless, I fully support the idea of getting this done, not to shout some mouths but because it's about time. People didn't get the "tooltips" idea... They'd rather have it in doc/help format... Well, maybe just leverage one thing with the other somehow. I wouldn't give up on the idea of using tooltips as something more than just tooltips, but don't make that to be the only/main documentation reference that comes with the software.

My 2c's

[Nocturnal]

Whatever gets put together needs to be installed with PI on the local drive. PI needs to have off-line documentation. My proposal to Juan was a single HTML file per process or module that gets displayed when a new 'help' button present on every process window gets pushed. The file would contain:

- purpose
- type of image this should be used on (linear vs. stretched, sharpened or not etc.)
- masking tips
- general workflow and tips (how-to-use)
- explanation of each GUI element including generated images
- external documentation (videos etc)
- literature references
- PCL and PJSR examples that use this process (optional but a good idea I think)

[RBA]

... by enhancing RGA's "Unofficial" guide

RGA? 

You're forgiven because on a star party yesterday someone who was asking for me went: "Hey have you seen this guy, RGB?"   

Of course after that someone went "yeah, RGB is there and I'm H-Alpha!" 

[Juan Conejero]

Hi Jack & al.,

Yes, this is precisely what I'm working on during my 'vacation' time: revise and extend RBA's guide to turn it into an official guide. A few days ago I contacted Rogelio personally to prepare my work on this topic. I take again the opportunity to say thanks publicly to Rogelio for his excellent and helpful work.

I like Sander's idea about a standard document structure. However I tend to be somewhat less 'formal' in this case because the same scheme cannot be applied to all tools, or at least not in the same way. But this is essentially the idea and we basically agree.

This revision/extension work will generate two sub-products:

- An official PixInsight Reference Guide, which will be available on our corporate website for public download. It will be available as a tree of XHTML documents, and will be updated regularly as new tools are created and existing ones are improved. This guide will also include brief practical examples along with tool descriptions, and extended information/discussions about key image processing topics (e.g. color management, RGB working spaces, multiscale processing, etc.). If you know the old PI LE documentation, then you can better figure out how it will be.

- A set of reference documents that will be included with all PixInsight distributions. This reference material, which will be basically the same available in the official Reference Guide (but organized in a different, more 'granular' way), will be accessible from the PixInsight Core application with a special, integrated help browser (basically a customized version of Qt's Assistant application). This is very close to what Sander has described.

So this is already (and will be during the next weeks/months) a work in progress. There will be an official user guide for PixInsight. This is an official statement

Regarding all of those recent forum messages about PI, I basically agree with Rogelio's point of view. It's pretty boring to say the least. Those of you that know me from this forum or personally, know also that I am always open to constructive criticism. I try to be a very self-critical person, probably too much in many instances, but I always prefer to have an excess of self-criticism to compensate for the dangerous possibility of self-pride. However, I never pay attention to destructive criticism.

Resistance to PixInsight --including some people trying to cause failure of the PixInsight project-- isn't something new to me. Recall that I'm in this 'business' since 2003. It hasn't been an easy way in any way since then. I think I have quite an accurate idea of the reasons behind that resistance. Besides the logical doubts and concerns of people considering the purchase of a new software tool --which I understand perfectly, and for that reason we have a trial license--, there are pathological reasons such as fear of what is new or different or unknown, and fear to lose what they (think that they) have, among others. PixInsight is all about not having fear at all. It is not to go against anything; it is just to build something new and powerful, to turn image processing into something exciting and creative. PixInsight is all about culture and development. Personally I feel stronger and more excited than ever in this project, so be sure that destructive criticism does not hurt me at all.

[mmirot]

I am sure it will be excellent  8)


Max

[sreilly]

Juan,

 Will either form of documentation be easily printable? There seem to be two camps on documentation. One needs the printed material in front of him/her (me) while the other does fine with reading off the monitor. For user manuals I usually either pay for the printed manual if it doesn't come with the product and is available or take the file to a place like Office Depot or other office supply store and have the file printed out and spiral bound. Then I just print out new and updated docs and add to the manual. It would be great if this were possible. I know with some documentation that isn't possible without opening the subject and telling the printer to print including sub-categories so this has to be done many times to print everything. This also uses way more paper than usual.

[Nocturnal]

Hi Juan,

well this all sounds excellent and I'm looking forward to it very much. Please consider how module writers can (should!) include documentation with their modules so it gets integrated into the installed documentation. That was one of the reasons for my per-module-html-file proposal.

[xatamec]

Complaints about PI not having an "official" documentation are getting boring - fact is, many people who fail to be productive with PI blame it on the docs when the reason is more because they're jumping on the software with a PS mentality or maybe because they think they can master the software in three runs or with little effort (as if they learned everything they know about PS in three runs also). It's been a while I put deaf ears on that kind of complaints (you can read them a mile away).

Aunque en lineas generales estoy mas o menos de acuerdo en lo que dices, poner oídos sordos a lo que dicen no los malintencionados a los que hace referencia Juan, sino muchos otros que han intentado acercarse a PI viniendo desde PS sería un error a mi entender. La naturaleza humana queda perfectamente descrita por el mito de la caverna de Platón. Podemos lamentarnos con mas o menos razón, pero la realidad es así y será así por los siglos de los siglos, así que en mi opinión cualquier estrategia en cualquier ámbito que obvie nuestro comportamiento como especie verá comprometidas sus opciones de éxito.

Saludos,
Sergi

[RBA]

Aunque en lineas generales estoy mas o menos de acuerdo en lo que dices, poner oídos sordos a lo que dicen no los malintencionados a los que hace referencia Juan, sino muchos otros que han intentado acercarse a PI viniendo desde PS sería un error a mi entender. La naturaleza humana queda perfectamente descrita por el mito de la caverna de Platón. Podemos lamentarnos con mas o menos razón, pero la realidad es así y será así por los siglos de los siglos, así que en mi opinión cualquier estrategia en cualquier ámbito que obvie nuestro comportamiento como especie verá comprometidas sus opciones de éxito.

En una empresa de 3 personas, es mejor tener a un licenciado en psicologia, un experto en ventas y un programador excelente, que tres programadores excelentes.
Cuando la empresa es uno solo (gran error en realidad aunque no quiero entrar en eso ahora), es bueno que el interesado se luzca en las tres disciplinas.

English: In a 3 people company, it's better to have an expert in psychology, a sales expert and an excellent programmer, than three excellent programmers.
In a one people company (a huge mistake, although I don't want to get into that now) it's a good thing that such person is really good at all these three things.

[Jaxdialation]

Is there a target date for getting the documentation done?

I manage 5,600 IT professionals in 4 countries 3,800 of which are developers. 
I've gotten in a bad habit of asking for dates      

There seem to be conclusions being formed regarding the psychology, motives
and even the character of those of us who want documentation.  Speaking for
myself, you are -way- off the mark.  And I might add I find these simplistic and
baseless comments offensive.   

 

[Harry page]

  Speaking for
myself, you are -way- off the mark.  And I might add I find these simplistic and
baseless comments offensive.   

 

Hi
From my view ( i.e. not official )

I don't think the remarks were aimed at you and are sorry that you are offended , It was not that justifiable comment about lack of docs was being voiced it was the tone that a particular person was taking.

If you read some of the threads here lots of PI users want docs so you are not in any way out on a limb here.


Any way welcome to Pi and look forward to you input

Harry

[Carlos Milovic]

Not official: Juan is working on the documentation. He is on "vacations" this month, so he is advancing at a slower speed.  I think that a first version might be available in September.

[Juan Conejero]

Hi,

Welcome to PixInsight Forum. I understand all the complains about lack of written documentation. I fully agree that a reference guide is necessary, and I am working to get it ready as soon as I can, as I have explained in a previous post in this thread. Regarding a target date, I don't dare say one because --everybody in this forum can corroborate this-- my reputation about target dates isn't the best one precisely

Jokes apart I think it may be presentable in a couple months or so, including a version of the documentation available in the core application. We have lots of priority tasks along with this one, and I can't stop development. There are lots of things to be done in the core application, new tools, improved tools, development tools, bug fixes, etc.

There seem to be conclusions being formed regarding the psychology, motives and even the character of those of us who want documentation.

I don't think so, at definitely not at all on my part. As I've said I understand and agree with all the complains about the need of a written reference manual. I personally think that there are much better forms of documentation and learning material, such as written tutorials and processing examples, and video tutorials, where I've been investing most of my --always scarce-- resources. However I know that a reference manual is important for a lot of people and hence there will be a reference manual. I've said and explained this sufficiently in this thread.

Harry has put it in its exact terms. The problem --for me, at least-- is destructive criticism. Saying that we should have a reference manual and criticizing PixInsight for that reason is OK. Saying that the lack of a reference manual is a serious problem that we have is saying the truth. I fully agree with that, and I am working to solve the problem.

However, saying that PixInsight is worthless because we don't have a reference manual is using a excuse to try to destroy the hard work and the illusion of others. That is destructive criticism in my opinion; I would never do that. I honestly think that PixInsight is a good software package. It is my humble work of many years and it probably isn't as good as it should be, but it deserves something better than a destructive criticism, even without a written reference manual.

So please don't be offended by anything I've said here because it was not aimed at you and, if you still feel I've said something offensive, please accept my sincere apologies and tell me what's it so I can fix the bug in the next release