Author Topic: Documentation  (Read 36579 times)

Offline papaf

  • PixInsight Addict
  • ***
  • Posts: 182
Documentation
« on: 2009 September 29 23:58:28 »
Hi all,
I'm about to buy my PI license. Will do in about 10-15 days. Money problems, you know...  :-\
But I'm not writing about that. I'm an avid CloudyNights forum reader, and I'm following a thread where the documentation of this fantastic app is discussed. I want to help. I am learning the program, and I'm coming from other (both easier and harder) programs as well. Plus, I have a big computer knowledge (I'm not a programmer, but a network tech, so I know my way around stuff). Do you think I can help? I thought, maybe while I'm learning, others could do that with me.

Tell me what you think about it.

Fabio

Offline Juan Conejero

  • PTeam Member
  • PixInsight Jedi Grand Master
  • ********
  • Posts: 7111
    • http://pixinsight.com/
Re: Documentation
« Reply #1 on: 2009 September 30 03:42:26 »
Hi Fabio

Welcome to PixInsight Forum.

Thank you so much for your nice words. I appreciate a lot your wish to help. As you probably have figured out, I am aware of the CN thread. Unfortunately, I never post on any public forum except this one. That's a price I have to pay for my involvement in this project.

The main problem here is not very original: time. Contrarily to what has been said, I cannot stop active PixInsight development because the platform still lacks a lot of key features. To put you in situation, these are the main pending tasks, by approximate order of priority:

- An image calibration system. We are implementing this as a set of JavaScript scripts. This task is relatively easy, but time consuming.

- Image analysis tools. We definitely need at least a tool to acquire PSF sizes and shapes, both manually (point'n shoot) and automatically (by star detection similar to StarAlignment).

- Project files. PixInsight projects will be XML files that will allow you to store the state of a running PixInsight instance, including all images and their processing histories, all icons, workspaces, settings, open scripts, etc., to recover it later. This is a difficult and delicate task, given the complexity of the platform.

- More generic image processing tools. For example, we still don't have a generic convolution tool, or feature detection tools. This is a shame.

- Improved development frameworks. The upcoming version 1.5.8 introduces important improvements to the JavaScript runtime (PJSR). We still lack a debugger for the PJSR, though. The core PCL/C++ framework is now nearly 5 years old and also needs some revamping. We need scripts to automate trivial parts of module development.

- Image editing and drawing tools, including a layered composition system with vector graphics generation capabilities. Many users want these features (partly due to their experience with other applications), and it certainly will make PixInsight a much more versatile platform. On the other hand, these features will open PixInsight to other fields of technical and creative imaging, which is the way to go to ensure that PixInsight will survive as a live project in the long term.

- Mosaic and panorama construction tools. The StarAlignment tool has excellent mosaic construction capabilities (it is urgent to show them with a video, BTW), but we need a dedicated mosaic/panorama construction tool.

- Improved core application GUI. The GUI must be in constant evolution to be more dynamic, more flexible.

And this is just a partial review. I am the guy behind this, but I also must do things like user support and some administrative tasks. For example, I must revamp the website ASAP because it is showing things that are two years old (look the screen shots section - another shame).

I do not stir up your compassion, by no means, mainly because I do just what I want and I extremely enjoy PixInsight development. It is just that I do what I can, and I try to do it well, that's all.

Having said that (sorry for the lengthy story), I agree with all of you who say that we need documentation. We indeed need to say what PixInsight does and can do, and in many cases we are failing in such a basic task. However, in my opinion the traditional "user manual" concept does not apply to PixInsight. The main reason is that PI is too complex, evolving and fast growing, so a manual would become obsolete too often. In my opinion, PixInsight documentation must consist of:

- Video tutorials. This is the best way to communicate knowledge about PixInsight, and where I am currently investing all of my documentation efforts and time. Something that requires hours of writing to explain it confusely, can be shown in a few minutes with a video, and in a much clearer and direct way. Harry Page (not Larry! ;D) is doing a wonderful work. I am in debt with him for his videos, absolutely.

- Written tutorials and processing examples. We have a bunch of these on the website, but some of them are now obsolete. An example is the LRGB tutorial that gave rise to the CN's thread. That tutorial is three years old and is mostly obsolete --in fact, I disagree with many things I wrote in that tutorial. For example, now I would *never* apply some selective corrections, especially the last one to apply an arbitrary color correction (just to make the image appear similar to the widely accepted vision of the object). My vision of astrophotography has changed since then, and we have now wonderful tools to achieve much better results with a much more respectful attitude toward the data.

- Basic descriptions for each tool. This is a work in progress. Descriptions will be included in the main application distribution in HTML format, and will be available from the Process Explorer window.

- PixInsight Wiki. This is a project that was suggested on this forum, and I want to start it as soon as possible. I have to enable PHP5 on our server to install a good wiki software, but I must make sure the existing scripts (including the whole licensing system) will continue to work well.

That's how I see it. I'll welcome all opinions and points of view on this topic, positive, negative or otherwise. Thanks for opening this thread!
Juan Conejero
PixInsight Development Team
http://pixinsight.com/

Offline papaf

  • PixInsight Addict
  • ***
  • Posts: 182
Re: Documentation
« Reply #2 on: 2009 September 30 04:09:25 »
Hi Juan,
unfortunately, as I said earlier, I'm no programmer, so I can't help with the coding per se. I have a lot of experience on computers in general, though, and with wiki systems too. As a matter of fact, I'm implementing one these days in our intranet here where I work. So, if you need help with that, I'm available.
Plus, I can write down some tutorials. Maybe, one starting point would be put Harry's video on paper, if he's ok with this. I can also produce videos, although my talked english is not really on par with the written one. Anyway, if a wiki is in sight, I would hold on to that because there's the risk of rewriting everything twice. And BTW, I'm greatly in favour of a wiki. It's great for documentation in general, but even better for projects like PI, where, as you rightly said, a manual is not what it's needed.

As I said, I'm available. This project really fires me up. Tell me how I can assist! :)

Fabio

Offline Simon Hicks

  • PixInsight Old Hand
  • ****
  • Posts: 333
Re: Documentation
« Reply #3 on: 2009 September 30 04:38:20 »
Hi Juan and Fabio,

This is an excellent thread!

Firstly, Juan....I think your focus on developing the software is spot on. The reasons you give in your reply are really convincing and I'm sure 99.99% of PI users back you 100%. So why not put some of this on the PI main webpage...i.e. on the homepage. This way, everyone will see this before they consider PI and will know where they stand. The fast pace of development is actually a really big selling point....so why not tell everyone. Otherwise you will need to answer these questions again and again on the forum. I know it will take a bit of time to craft the right words for the homepage, but it will save in the long run.

Also, your description of all the upcoming roadmap items is really impressive...and exciting. Again, this is a really big selling point of PI. Why not put this on the homepage as well. I really like PI because it is 'going somewhere'....so this would be nice to see. It would also be great to see all the new features in all the new versions on the webpage. I think the Stark Labs web page is a good example....you can see all the revisions happening, so it helps you see that there is constantly exciting stuff going on. Maybe it could just be links to the release information that you give out on the forum. It would be really cool if the homepage had news items that included the latest scripts being published on the forum....but this would be more hard work.

I think one of the biggest selling points of PI is that you become part of a club or a project that is really going somewhere.

Please take all of the above as just my ramblings, and I'm fine if you think I'm on the wrong track.....just thrpowing ideas in the pot.

Secondly, Fabio: a wiki would be great. If it was easy to use then at last I would feel I could do something to help out.....I can't do any of this programming stuff....I wish I could!

Cheers
       Simon

Offline Juan Conejero

  • PTeam Member
  • PixInsight Jedi Grand Master
  • ********
  • Posts: 7111
    • http://pixinsight.com/
Re: Documentation
« Reply #4 on: 2009 September 30 07:05:15 »
Hi Fabio,

Making written tutorials from Harry's videos seems an excellent idea to me. Let's see what Harry says. I think both versions -video and written- could be put together for each tutorial.

I'll probably need some help with the wiki, so I count on you. My intention is to install MediaWiki. What do you think? Is this the best option, or do you know something more appropriate?

Regarding spoken English, I have exactly the same problem. I can write it reasonably well (I think), but I am almost unable to say anything understandable :laugh: Now you know why my video tutorials are all talked by Alex, the Mac voice. Good guy Alex :)

I am glad to know you're being fired up by PI. That's the idea ;)
Juan Conejero
PixInsight Development Team
http://pixinsight.com/

Offline Juan Conejero

  • PTeam Member
  • PixInsight Jedi Grand Master
  • ********
  • Posts: 7111
    • http://pixinsight.com/
Re: Documentation
« Reply #5 on: 2009 September 30 07:18:22 »
Hi Simon,

Thank you for pointing this out. I completely agree with your opinions about the current website: It should be offering much more dynamic and up-to-date contents. PI deserves something better than a page that shows "news" from a couple years ago. I must admit I've neglected this aspect, and it is very important. Time to renew PI's website!

And definitely it's also time to start the PixInsight Wiki project. A wiki is very easy to use. You just have to write the contents with a web interface that is quite similar to a word processor (also similar to this forum's message editor).
Juan Conejero
PixInsight Development Team
http://pixinsight.com/

Offline papaf

  • PixInsight Addict
  • ***
  • Posts: 182
Re: Documentation
« Reply #6 on: 2009 September 30 07:30:58 »
Mediawiki was my choice too, so I know it well. It seems to me it's the best out there, so no complaints by me! ;)

Fabio

Offline Harry page

  • PTeam Member
  • PixInsight Jedi Knight
  • *****
  • Posts: 1458
    • http://www.harrysastroshed.com
Re: Documentation
« Reply #7 on: 2009 September 30 10:17:38 »
Hi People


As you say juan more uptodate information would help at the front end of your web site would encourage the non believers ( Yes photoshop devil worshipers  >:D ) to take the plunge.
This was always the idea of my simple video's feeling that people needed to get some fairly quick results or they loose the plot  ??? , once you get going you realise how basic they are , and I need to do some more intermediate video's as my skill level gets better  :D
A few people Say Mr pixinsight should be grateful of my video's and it is nice when people say thanks ( Gives me job satisfaction ) , but this is not the reason me and others ( HI sander) do such things , it as simon says to help the club along and to return the help so many other people have kindly given me in the past.
I look forward to a wiki thingy ( I leave the tech bits to brighter people than me ) and look forward to contributing

I have no objection to anybody using / writing anything to go with my tutorials ,  :P and if you think it would help go for it

Harry

Harry Page

Offline georg.viehoever

  • PTeam Member
  • PixInsight Jedi Master
  • ******
  • Posts: 2132
Re: Documentation
« Reply #8 on: 2009 September 30 10:24:44 »
Hi,

the problem with PI is not that there is no documentations. It is just spread in so many different places: Forum articles, bubble help, website, PixInsight LE, videos, ... Just collecting those links and structuring them into specific topics would be a huge help.

My own experience with Wikis is not so positive. After an initial enthusiasm, they tend to get out of date. I have seen this many times. Wikis need a somebody who does structuring, cleanup, updating. I am not sure if a Wiki will work better for PI than for other tools.

Georg
Georg (6 inch Newton, unmodified Canon EOS40D+80D, unguided EQ5 mount)

Offline Silvercup

  • PixInsight Addict
  • ***
  • Posts: 187
Re: Documentation
« Reply #9 on: 2009 September 30 12:39:45 »
Hi:

I agree with everything said. Web must be renewed and try to gather all available resources, tutorials, videos, useful codes, etc.

You can count we me as needed. I know PHP programming if it helps.

Something that has not been done is post the videos on youtube, there are only two from C. Sonnestein.

Greetings. Silvercup.

Offline lucchett

  • PixInsight Old Hand
  • ****
  • Posts: 449
Re: Documentation
« Reply #10 on: 2009 September 30 14:58:04 »
a way to organize froum discussions by objects would be helpful in my opinion.
lot's of time I know the answer is there but I can't find it.
I am sure technology can help here, a sort of mind manager to organize threads by tags...

at maximum having different kind of learning objects (articles, tutorials, videos, forum threads) grouped and organized by tags.

Ciao,
Andrea

Offline papaf

  • PixInsight Addict
  • ***
  • Posts: 182
Re: Documentation
« Reply #11 on: 2009 September 30 23:10:39 »
Georg, I know what you're talking about regarding outdated documentation. It happens when a product such as PI gets constant update, and it should be one of our primary objectives to keep it all in sync with the program itself.
Having said that, I think wikis have nothing to do with documentation being outdated. If anything, wikis are so easy to edit that they are actually easier to update than, say, normal html pages or worse yet, pdf documents.

In short, I firmly believe outdated documents are not related to the instrument used to write or publish them, but just to the people who should write and update them.

Fabio

Offline Simon Hicks

  • PixInsight Old Hand
  • ****
  • Posts: 333
Re: Documentation
« Reply #12 on: 2009 October 01 00:57:01 »
If we had a wiki....would it be possible to place links in each Processes or Script to the relevant section of the wiki. So for example, if I open up the AtrousWavelets process, then somewhere in that window there would be a button that would take me straight to the wiki section on how to use AtrousWavelets. It would not take too long to put such a button on every Process and create links to empty wiki sections. Then each of us could grab one of these sections and start filling in the relevant wiki info. It would get populated in no time.

Maybe that's what you were already thinking. Just a thought.

Offline mmirot

  • PixInsight Padawan
  • ****
  • Posts: 881
Re: Documentation
« Reply #13 on: 2009 October 01 07:32:31 »
Juan and all,

1 Excellent road map Juan!

2 First, thanks to all software contributors.
   This is one reason why PI is unique and has advantages over other platforms.

   How often do you see a piece of software is developed and released with a few days or weeks in  responding to a forum discussion?  
 
3 I have yet to find a good forum/Group sharing Photoshop techniques for astro-imaging.

4 There are a variety of PS astro and non astro techniques.
    However, they are scattered over cyberspace as well.

  The standard manual for Photoshop is basic and rather cryptic.  It never helped me at all
   So You have to look hard for good documentation on PS IMO.

5  Books and Videos by Adam Block , Ron Wodoski, Dale Ireland and Warren Keller have been the real teachers.  However, I did have to pay them for their efforts. and
They had since the mid to late 90s to get it together too. ( I don't regret buying the books, btw).  

6 Many of these guys were taught by graphic artists or photographic professionals.
PS is big software package and you can take college level courses and seminars on it.
It has been that way for a long time.
I heard Rob Gendler ( a great imager ) actually spent sometime with Tony Hallas being tutored with PS when he was starting in the mid 1990s.
Tony hallas has/had a professional photo lab as well as being a top astrophotographer.
I am pretty sure his expertise did not come from the PS manual. Perhaps years of trial and error.
I know Dale Ireland took photoshop courses to get started



8 The documentation issue need to put in perspective.

Photoshop is twenty years in the making with lots formal education now disseminated.
Some of this info has found its was home to astrohotography.  
Next it took a lot trial a error by thousands of astroimagers perfect many techniques.
It took a long time to do so and was not because of the manual.

9 PI has an group of avid inovators, users and teachers.

It smaller group but infomation is starting to snow ball with more contributions all the time.
This excellent considering it still has only a few hundred users and no real advertising. Just word of mouth.
The informatation is now being disseminated more rapidy but in a less traditional manor.
For those that actually join the forum,  it has become easier with many recent contributions including videos.

10 Nevertheless, we need a Wiki or something like it to centralize this infomation.  It does not matter if it is a full tutorial or just a helpful post.

Also, more updates on the main web page. We have to let the world know what Juan and other are doing on regular basis.

A lot of the information on the forums are great advertisements for potiental new users too.  This includes update anouncements with examples of the new features.



Bottom keep on pushing. We are doing great. I see more APODs and published images using PI all the time
If you have been using PS sucessfully for ten years I don't expect you to jump ship to PI overnight.

There is plenty of time to invested in learning a new platform that has it own complexities.
The learning curve is very similar in amount of time it takes to get the ball really rolling between PS and PI.
On compartive basis PI has it is strengths and weaknesses compared to PS.  

My three cents.

Max
    
Where can I find the CN thread? This should be interesting
« Last Edit: 2009 October 01 08:48:59 by mmirot »

Offline Carlos Milovic

  • PTeam Member
  • PixInsight Jedi Master
  • ******
  • Posts: 2172
  • Join the dark side... we have cookies
    • http://www.astrophoto.cl
Re: Documentation
« Reply #14 on: 2009 October 01 09:20:07 »
Look under the CCD subforum
Regards,

Carlos Milovic F.
--------------------------------
PixInsight Project Developer
http://www.pixinsight.com