Documentation

[mmirot]

More...

I think much of PI is mature enough that much of documentation on the basic interface and modules will not need to be modified frequently. We should know what each imput or slider does.
Juan has little bit of this information on some modules in the form of roll overs. Real documentation would be more complete.

For example,
Which direction do I push the slider to sigama reject more pixels in integration, one or ten?
How do I analyse the High/Low Reject maps.
These explainations do not have to go into greatest detail.
That's were the Wiki and formuns pitch in.

The are still many aspects of basic interface I don't use because I don't understand it or know it is even there.
ie histories, saving projects-module Icons icons, recovering a autosave, optional settings, running the script box, image container.... etc.

Max
  

[georg.viehoever]

Hi Sander,

I could not agree more with you. Yes, good software requires documentation, with all the benefits that you mention.

But:
- PI core development seems to be very much a one man show run by Juan (with occasional support by others)
- Juan made several attempts towards improved documentation (his videos, even the beginning of a written documentation that unfortunatly disappeared from http://www.pixinsight.com/, serveral processing examples, ...). But somehow, he always decided that other topics were more important, such as new processes, Wiki, Bugtracker, .... : I don't know if these priorities are always wise, but they certainly created a lively Pixinsight Forum
- As a developer, I can certainly relate to giving priority to code (while having a bad conscience, though....)

PI has many aspects of a community project (while at the same time being closed source). Why not work the same way as many community projects for documentation?

Georg

[Simon Hicks]

Sander,

Built in module help will require the following:

1) design the framework (I believe Juan intends to create a separate doc directory in the PCL tree)
2) define the documentation template (Juan and I discussed this over email, nothing fancy)
3) implement the 'push a button and show an HTML page or dialog that says no page is found'
4) start writing

Because of this 'architecture' documentation can be updated and delivered incrementally.

Wow, this sounds perfect!

I was worried that we were just talking around what should be done but coming to no real conclusions or actions. I think (maybe I'm wrong) that that is where Georg was coming from as well.....there's this overwhelming wish by everyone to get good documentation....but we all know Juan is writing code (whether he should be or not). So to see a real positive structured move like this is great. I think Juan needs support like this...i.e. like the structured suggestions you are giving him.

My worry is point number 4 in your list. Who does the writing? Will it be done? Are we back to square 1? How do you see this panning out?

Cheers
           Simon
 

[Cheyenne]

There is another aspect to the documentation.  A professional's view vs a layman's view.  

First, I would say that PixInsight leans towards a professional audience.  What I mean by this is that the features and capabilities of PixInsight are targeted to someone who has had formal education in image processing and understands the concepts behind many of those "magic sliders and buttons".  That is the power of PixInsight.  I also suspect that if much of that power where "hidden" behind "wizards" or automated cook-book type of scripts, it's appeal to a professional community would be diminished (personal opinion).  

So what does a professional need to know in terms of documentation.  Simply what the button or slider does, expressed in "industry standard" terms.  Personally I have found that I can figure out what is going on for many of the facilities within PixInsight by diving into some formal image processing books that I have at hand, or by poking around ACM articles on imaging processing (image processing is not an area of computing that I haven't spent a lot of formal time in).

So.. here is what I think PixInsight needs. PixInsight needs some documentation targeted towards a layman's view.  And again I believe this leads back to explaining the why's of things or giving guidance selecting the processes and guidance on setting the parameters.  I guess what's lacking is a "O'Reilly PixInsight in a Nutshell" book (for those not in computers, O'Reilly is a publisher of technical books that while some are targeted towards professional use, many are targeted towards someone who may need to apply a certain technology or science, but doesn't need to understand "how" it works, for example "Statistics in a Nutshell").

[Fco. Bosch]

I'm not sure, but I think that there is also a matter of language. It is liquely that a spanish documentation would be much fast to make than an english. If someone cuold then traslate it ... 

[Fco. Bosch]

I'm not sure, but I think that there is also a matter of language. It is liquely that a spanish documentation would be faster to make than an english. If someone cuold then traslate it ...  Grin

Qod erat demonstrandum ...

[Juan Conejero]

... that a spanish documentation would be faster to make ...

Sorry, but if you're referring to me, I always tend to think in English when I sit in front of a computer. For example, almost all of the tutorials I've written have been authored in English, then translated into Spanish. When it comes to writing technical documents, English is my natural language.

Having said that, I must recognize that my spoken English is one of the worst ones I know of,  to be honest. You really don't want to hear me speaking English

[Juan Conejero]

OK guys, so it seems you're cooking something here

Let me finish the next version, which I am almost ready to release, and we'll talk about this topic seriously.

Following Sander's schema:

1) design the framework (I believe Juan intends to create a separate doc directory in the PCL tree)

Correct. My intention is to release a first version of the integrated documentation feature with PI 1.6. As I see it, we should have a system similar to Doxygen, but adapted to PI's specific requirements. What I want is a standardized system where the contents and the appearance are perfectly isolated. You just write the contents, then the framework creates the presentation. That's an information content manager. Of course, I'll implement this as a JavaScript script, similar in concept to the MakefileGenerator script.

2) define the documentation template (Juan and I discussed this over email, nothing fancy)

This actually forms part of the previous point. More than a template we'll have a —very simple— macro language to write documentation items.

3) implement the 'push a button and show an HTML page or dialog that says no page is found'

Let me do all the nitty-gritty. I have to decide what to use, since I have several good possibilities. Integrating Qt's Assistant application (a hierarchical HTML-based documentation manager) seems a good approach.

4) start writing

Aha. This is the hard core part, and here is where I'm gonna need some help!

As I've said, let's release the next version, then we'll talk more. Thank you guys for your help and all your fantastic contributions.

[Harry page]

Hi

Sorry late into the quest again

Yes I do believe the interface is slick enough for the time being and should be left alone for a while .
Even though I agree that documentation is very high on the must have requirements, there is is still a few modules urgently required , mainley being the
calibration module.
Back on the documentation track I agree that layman's terms and real world interpretation are important and the overuse of big words is to be avoided for the simple
people like me 

Regards Harry

P.s.

Andrea
I did do a couple of mask videos    http://www.harrysastroshed.com/pixinsighthomeinter.html
might not be what you are looking for 

Might

[Niall Saunders]

And if I can also just jump in as well - I know that I have made several posts where I said I would try and get a PJSR up and running for 'Calibration', however I simply seem to have been swamped by other (personal) events recently. But, I will keep trying - to at least get a 'framework' up and running - and we can move on from there.

Apart from that, I agree with the general consensus that now is the time to 'take stock' of what PI has become. The new Website, the Wiki and formal Documentation are three areas that are now overdue for attention. And all three of these areas are so closely related that their development is NOT mutually exclusive. Whilst developing these areas, new ideas will emerge - and it will be these new ideas that will be, and should be, the foundation for the 'next generation' of PI.

Cheers,

[mmirot]

... that a spanish documentation would be faster to make ...

Sorry, but if you're referring to me, I always tend to think in English when I sit in front of a computer. For example, almost all of the tutorials I've written have been authored in English, then translated into Spanish. When it comes to writing technical documents, English is my natural language.

Having said that, I must recognize that my spoken English is one of the worst ones I know of,  to be honest. You really don't want to hear me speaking English

Juan, You write better in English than I do.
I am medical doctor we are not considered literate by most authorities.

Max 

[Fco. Bosch]

Sorry! but all that I said yesterday is that to write a book -like is the manual of PI - in a foreign language is normally much more difficult than to write it in the own language ... Nothing more, except an idea for to help Juan in their work for to write the software and the book 

[Juan Conejero]

Francisco, no lo tomes así por favor, que mi intención no era menospreciar lo que decías en absoluto.

De hecho, lo que dices es muy cierto en la mayor parte de los casos. En el mío sin embargo, me resulta más fácil escribir en Inglés cuando se trata de textos técnicos sobre programación, desarrollo de software, o procesamiento de imágenes. Hay varias razones para esto, la principal es que después de leer muchos miles de páginas de textos técnicos en Inglés, y de escribir también muchos miles de líneas de código fuente en el mismo idioma, pues algo se te pega por fuerza

Pues eso, que mi respuesta me parece que fue un poco brusca, pero aquí se agradecen todas las aportaciones.

[Fco. Bosch]

tranquilo Juan; me di cuenta después de que mi texto, por estar escrito en inglés, no era todo lo expresivo que debiera.

[Nocturnal]

Correct. My intention is to release a first version of the integrated documentation feature with PI 1.6. As I see it, we should have a system similar to Doxygen, but adapted to PI's specific requirements. What I want is a standardized system where the contents and the appearance are perfectly isolated. You just write the contents, then the framework creates the presentation. That's an information content manager. Of course, I'll implement this as a JavaScript script, similar in concept to the MakefileGenerator script.

You have an unsurpassed capability of complicating simple things Juan Here's my proposal:

- when the 'help' button gets pushed (or hotkey gets pressed), display an HTML file doc/ModuleName.html in the system browser.

Poof. A few hours of coding, tops. Move on to actually *writing* the documentation in a language we already know, HTML. Use a common CSS file to make sure all help files look the same. More importantly it'll be easy to explain to PCL developers how to write the documentation. Use this HTML template. I mean this is not rocket science, right?

Javascript? Information Content Manger? KISS Applies here. LOWER the barriers to writing documentation. Don't put barriers in place. Please.

Worst case scenario is someone write an HTML file that doesn't look 'good' or misses a few sections. So you reject the module for inclusion until that's resolved. Modules 'in the wild' are not sanctioned so there we'd be happy to get any documentation at all.