Documentation

[Nocturnal]

Thanks for kicking this off. I was away on vacation so I didn't see the thread blossom. While I think the wiki is nice it does not constitute documentation. Documentation should be available off-line and directly accessed from within PI. I see a need for at least three types of documentation:

1) basic 'this is what this process is for, here's what this button does' stuff. This *needs* to be included with PI when you install it. Every module requires a help file. Without this PI will never get over the stigma of 'expensive software without documentation'. I've suggested to Juan in private email to create an HTML template for each module that contains a number of pre-determined sections. The HTML file should be displayable from with a simple button push in PI. Display can be in the default browser, that part is immaterial. I'm pretty sure Juan is on-board with finally biting the bullet and doing this.

2) tutorials and walk-throughs that tie modules together into processes. Examples that show how particular problems can be solved. This is well suited for a wiki.

3) release notes. These are currently posted in the forums but frankly that's not where they belong. It should be easy to find out for a new version what is, well, new. If you skip a few updates it should be easy to find out what new features you got by reading all release notes in between the two versions. I think this should also be included in PI. It can also be posted in the forums for announcement and discussion purposes but forums ARE NOT documentation.

I maintain the qhy8 and deepskystacker wikis so I know what they are useful for. I think the PI wiki can fullfil a similar role but can not take the place of actual documentation written by authorities. Wikis, by their very nature contain not just fact but also opinion. Documentation should avoid that as much as possible and be neutral in tone.

[Cheyenne]

Here is my take of the wiki.

I don't think the wiki as a substitute for the actual product documentation, but as a collective set of margin notes for the product documentation.  As individuals use the product and notice certain things, they can annotate the product documentation via the wiki. 

The wiki can also be used as an interim facility to fill in the gaps for lacking documentation, where the product authors (Juan & company) may have provided reference documentation, but not a "how to use" documentation.

There are two types of documentation.  Reference (just the facts, this field takes values from 0 to 10) and User Guides (how to use something, this field will alter the contrast of an image, higher numbers will have a higher contrast).  References are great if you already understand the purpose of the function, while user guides are more helpful in learning how to use something.  As an individual becomes more familiar with something, the user guide becomes less important.

Right now I believe that the current state of the Official PixInsight documentation leans more towards the "Reference" side of things.  There are some functions that are providing "user guides", but I believe overall to the entire product it's incomplete (and I'm not "blaming" Juan & company -- they have been very very busy providing some very outstanding functionality in their product and I would rather see them spending their efforts in building even more outstanding functionality).

To give a good example of a Reference type of documentation, take the Histogram Transformation process module.  If I hover over the the different fields I get "help" that says "Auto Clip Shadows" or "Shadows Clipping" which is 100% correct - that's what that button or field does.  That particular button will auto clip the shadows, or the field will set the shadows clipping value.  But it doesn't tell my why I want to use the Auto Clip Shadows, or any guidance on how to pick a good value to set the Shadows Clipping value to.  A "User Guide" will help me understand when I want to use certain options, or what the meaning of the values are. 

I believe that the wiki can help Juan & company by allowing the users to work on the "User Guides".  There are folks out in the user community that really know what the meanings of some of these fields are, and why one might want to adjust the values, or what *good* values are in a given circumstance. As a consensus forms around these descriptions, Juan & company can pull some of the information from the wiki and incorporate it into the product help files.

Anyway -- that's my take

[Nocturnal]

Hi,

I actually think there's a third type of documentation, the 'cookbook'. I have cookbooks for VB.NET, ASP.NET, Ruby, SQL and others. They are my favorites because they describe problems in terminology that a beginner can understand. The problem with references and often user guides is that if you don't know what you're looking for how will you find it?

I think most of our current documentation is in the cookbook style. Videos and articles walk you through typical processing sequences, sometimes glossing over details to avoid overwhelming the reader. Tooltips in modules are nice but I don't think they qualify as reference. Their quality is too variable. Some are very complete, others are missing altogether. Some are inconsistent with actual behavior. I think tooltips should be exactly that -TIPS-. Not novels. One sentence should be enough to remind someone what the option is for. More detail should come from the user or reference guide for the module.

As far as the wiki is concerned I think each module should have a page where FAQs, tips 'n tricks and user comments can be gathered. The actual reference should go into PI. The Process Explorer already has a 'Browse Documentation' button but it's not active. I think it can be removed. Instead each module should have a new standard button at the bottom (or wherever) that brings up the documentation.

[Simon Hicks]

each module should have a new standard button at the bottom (or wherever) that brings up the documentation.

Yes please! Big time!

Would it be possible for this button to link to the relevant module section of the Wiki? I'm not sure if that is what you are suggesting. If it is, then I would really like that.

[Nocturnal]

No, I *specifically* don't want that 

As I argued before, I want PI to come with off-line documentation. The help menu can (should?) contain a link to the wiki and the individual documentation pages can contain links to wiki pages but clicking 'help' should work when I'm flying cross country, so to speak

[Cheyenne]

I agree with Nocturnal, while a pointer from PI into the wiki is fine for "hey there's a wiki over there", pointing into the wiki for raw documentation would cause major "breakage".

I think that your concept of a cookbook, is kind of a user guide.  A user guide should be "readable".  It should be topical, "how do I combine a bunch of images", "how do I remove noise", "how do I fix bloated stars", etc.

I think your idea where each module should have a page where FAQ's, tips n' tricks, is exactly what I had in mind for the individual processing modules pages.  The "Processing Steps" would be the anchor for cookbooks / user guides.

[georg.viehoever]

I agree that reference documentation should be part of the product. But who but the makers of PI should create this?  In my eyes, the Wiki is a way to support the PI makers by making part of the documentation task a community effort. Are we, as current or future PI users, willing to pay for a documentation writer? Or would we like the PI makers to spend our money on improving the software itself?

Quite frankly, I am a documentation addict, and I would very much like to see more PI documentation. But would I like to spend more money? I am not so sure...

Georg

[Simon Hicks]

I guess I was coming more from Georg's angle. And I guess part of this is from my inexperience with WIKIs in general and maybe a different expectation of what it would be used for (maybe unrealistic).

What I would really like is the button in each module that Sander refers to and it give me the help I need....not just a two-word parameter definition, but something more beefy. And a good introduction to the module in general. I thought the WIKI might give us that level of module definition and help as supplied by the users. In a way it would be giving Juan the source of material that he would either link to or copy / paste / edit and include with PI....so Sander can access it on his private jet when he's flying across country ( ....only joking....I actually agree with the off-line support idea).

As I see it we all want great documentation, we all want the hints, tips and tutorials, we don't want Juan 'wasting time' on documentation when he could be bringing out the next fantastic new features, and finally we don't want to pay extra to have someone write documentation.

I wonder if the only solution left is for members of the 'community' to volunteer to write little sections of documentation (i.e. we each take a module???) and we use the WIKI to polsih it up and then Juan just copy and paste it into the off line version of PI....i.e. connected to Sander's "I'm on my Jet" button. Just a thought.

[Cheyenne]

Simon, I think you got the idea behind wikis.  As a community, we improve the information for all of us. 

And it's not so much that everyone go grab a particular module and write doc, if you have a tip, or some knowledge of a function, go out and edit the page.  Don't be afraid of writing something "wrong", it can always be updated with better information.  View it as shared learning

[Nocturnal]

I don't see documentation by module authors as a waste of time or money in any way, shape or form. For just about every commercial and even open-source/free product out there at least rudimentary help is mandatory. Not optional. At this point I do not want more fancy modules without documentation. It's like having a fancy car in the driveway but not being able to drive it because you have no keys.

PI's functionality (both look/feel and module set) is terrific. I does not have to be more terrific just yet. I want the current PI solidified with documentation. I'll even put my desperate wish for projects on hold for it.

Next year I'm going to present PI at MWAIC. If it doesn't have help by then I'm not going to be a happy camper because people are going to smack me around the ears with that. And they should.

[Simon Hicks]

I don't see documentation by module authors as a waste of time or money in any way, shape or form.

No, nor do I Sander, don't get me wrong. I guess the issue is that there's a whole pile of already written modules that could do with a bit more help attached to them. So the question is....how does that get done for the off-line version.

The easy answer is to pressure Juan to do it.......and now you have made the point....I guess I can agree that it would be acceptable to stop the new fancy development for a number of months and for Juan to concentrate on playing catch up with the help. PI is "different" and therefore the help is all the more important to getting new users hooked. I'm most interested in having in-depth help on each module (and script)....at least that is the priority as I see it....others may prefer the tutorials etc to be done first.

I just feel that there may be a way to have our cake and eat it.....i.e. there may be a way for us to contribute to creating the help material....at least for the modules....and therefore speed the whole process up. But this would have to be somehow structured. Hence my idea of each of us taking on one module and writing a standard format help file around it.....intro, detailed function descriptions, typical usage, etc. Once we are happy, these could be submitted to Juan for inclusion in the next release....i.e. connected to the help button on each module.

But maybe this is too complicated and we should just leave it to Juan???

[lucchett]

Hi all,
my impression is that the requirements in terms of "documentation" change a lot depending on PI users, skills and other software used.

My personal point of view is that the first customer here are the people who already committed to PI and use it daily.
I think the right way of approaching this is collecting the voice of the customers through an online survey to basically asses and balance two things:

-what the current user feel is still missing
-what we think is mandatory to guarantee the development of PI in the future (new users..): here, I think the PI team has his ideas on the Customer profile of the future user; Pi is different form other software and I have lot's of friends that won't buy it ever, because they don't understand english, don't like the mathematical approach, don't wan't to invest much time in processing, or simply are computer-allergic.

Just to contribute with my personal "vision":

-the tutorials are great, even if not updated-
-what is missing in the tutorials is probably in the forum: there's lot's of value here but the issue is that is painfull to look for example for everything about masks.
-videos are great too, but especially for new PI users in understanding the modules: normally the video doesn't help you with a real  life processing where you need to tweak all the parameters or follow  a completely different approach for that particular image (see star masking..)

If we could put hyperlinks in the tutorials to the forum threads and put tags in the threads it would  be very good.

As PI user what I still need is someone that create a tutorial from Forum's discussions/old tutorials about:

-masking
-star masking
-channel splitting /recombinig, RGB space selection

The you can concentrate on perspective customers and traditional help resources that seems mandatory for them.

Again, this is my personal view on this subject.
Regards,
Andrea

[mmirot]

Saunder you are right.

It is time for documentation more than new features.

I am not sure I am getting the most of many of modules released.
For example, we had a forum thread on the best settings for integration for calibration images.
We have not had much information on the best setting for light frames.

Perhaps Juan could afford to hire Georg 

[georg.viehoever]

...
Perhaps Juan could afford to hire Georg  
...

I am way toooooo expensive  

Georg

[Nocturnal]

Hi Simon,

I was referring to Georg's post that seemed to suggest there is a trade-off between new PI development and documentation. I strongly believe documentation is an integral part of development. Writing documentation forces you to look at your product through your customer's eyes and this can be very enlightening. In fact, lacking any formal requirements and use-case analysis before development starts it's a good idea to write the documentation first and then the code. Actually it would be even better if the tests were written right after the requirements are done. For my professional development I try to write my unit tests first to reproduce a bug or prove that indeed a new feature does not work. Then add the code that needs to be written, re-running and refining tests as I go.

But I'm getting off-topic

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.