Skip to main content

VStar User Manual Project

We recently released a significant update to the backend systems for the AAVSO website. While most of the bugs introduced by this update have been fixed, there may still be problems we haven't fixed. If you run into a problem, please email webmaster@aavso.org
David Benn's picture
David Benn
Offline
Joined: 2010-07-29

Hi all

As you all know, the current VStar help (Help -> Help Contents...) is pretty minimal and I've been meaning to do something about this for quite awhile. I could say that my focus has been more on functionality and bug fixes than anything else, but that's really just an excuse.  I've written a fair amount about VStar here and in other places, such as my blog, newsletters, and an eJAAVSO paper (see the links in the Help! section at the end of  http://www.aavso.org/vstar-overview or https://sourceforge.net/p/vstar/wiki/Home), given talks at Citizen Sky, NACAA and a couple of astronomical societies.

Let's face it, what's needed, more than anything else, is a da da daaaa... user manual!

So I'd like to propose a community-based user manual project for VStar to which anyone can contribute upon request. It would be:

  • Google Docs based.
    • A VStar Docs folder has been created and I will start to populate it soon.
    • I will share the document to anyone wishing to contribute a section or chapter or be a reviewer or proof reader. Options are to share the document URL to whoever asks. Another is to require Google login before the document can be updated. I recently wrote a paper with several other authors who had to be logged in. I think that worked well because we could see who was working on the doc, who was adding review comments, could chat to other authors etc.
  • Split into separate documents per major section.

When "complete", it would be exported as Word/PDF for distribution. Whether it stays in Google Docs for future revisions or moves to SourceForge+Subversion is an open question. That's where the plugin development document currently is (https://sourceforge.net/p/vstar/code/960/tree/trunk/plugin/doc).

My role would be to:

  • Coordinate the overall structure of the document.
  • Contribute some of the content.
  • Act as "lead author", looking at coverage and consistency.

One of the benefits of others writing sections of such a document other than spreading the work around, is that it will generate questions about how things work that I take for granted. It may also find bugs.

Please let me know what you think.

No matter how many people show interest, I will almost certainly start taking this approach to creating a user manual anyway. I would welcome input and contributions from the VStar user community.

The next post will propose an initial table of contents.

David

Proposed Table of Content
David Benn's picture
David Benn
Offline
Joined: 2010-07-29

Okay, so now that everyone's all fired up about writing a section of the VStar user manual :P, here's my suggestion for an initial table of contents:

  1. Introduction
    1. Brief overview
    2. Introduction to main window, tabbed panes, menus and toolbar, raw vs phase plot mode.
    3. Further reading: links, books
  2. Observation Sources
    1. AID
    2. Download and simple format files.
    3. Plug-ins: give one or two examples and point to plug-in library page.
  3. Info dialog
    1. Name, type, ...
    2. Bands
    3. Period
    4. ANOVA
    5. Confidence Interval
  4. Saving and printing
  5. Panning and zooming
  6. Plot Control Dialog
  7. Observation details and discrepant reporting
  8. Filters
    1. Creating
    2. Managing
  9. Working with the observation list
    1. Sorting
    2. Searching
    3. Selection filters
  10. Undoable edits
    1. Observation exclusion
  11. Creating and managing phase plots.
  12. Polynomial fit
    1. Band and degree selection.
    2. The model and residuals panes.
  13. Phase plots
    1. Creating
    2. Managing
  14. Period analysis
    1. DCDFT
    2. Creating and managing models
    3. Finding harmonics
    4. CLEANest
  15. Time-frequency analysis
    1. WWZ
  16. Scripting VStar
    1. API
    2. Examples
  17. Plug-ins
    1. Types: observation source, filter, period analysis, tool, ...
    2. AAVSO plug-in library.
    3. How to develop: point to existing document or incorporate it.
  18. Preferences
  19. Authentication
    1. When is it required: some plug-ins, discrepant reporting.
  20. License information
  21. Index

Initially, I intend to create a document in a Google Docs folder for each top-level item.

Feedback please!

David

Great!
Matthew Templeton's picture
Matthew Templeton
Offline
Joined: 2010-03-12

David,

This is great, and I wholeheartedly encourage it -- VStar is a phenomenal resource.  I'm happy to help add material on time-series analysis where needed.

Thank you for taking the lead on this, and VStar itself!

Matt

VStar Manual
mqe's picture
mqe
Offline
Joined: 2010-07-08

 Hi David and Everyone:

 

I'm working on the VPHOT manual.  I have several hundred pages so far..it has not been edited by Geir yet for content and HQ for format, etc...but if you would like to see what I have from a format point of view, I would be happy to share what I have so far in Google Docs with anyone.

 

You might want to look at whether what I chose to do with highlighting things with images will work for you.  If so, I can give you some pointers on how to get the effect.

 

One of the disadvantages I found using Google docs was that, if you choose to write what you are doing first in Word or PPDF..you cannot simply copy and paste what you have done into Google docs if you have images mixed in with the text.  You can only do 2 MB at a time, and there is a trick to getting the images to transfer (basically you have to use "control C" not "paste"--assuming you are working from a PC like me...not sure what happens on a MAC).

 

There are of course advantages to editing directly into Google docs...but I did lose a lot of stuff twice, so if you go that route...be sure to back up what you do in Google Docs.  Then you can reload if you lose stuff 2 MB at a time.  I eventually found it easier to just copy and paste into Google docs.

 

Cheers,

 

Ken Mogul (MQE)

Thanks Matt! I know you're
David Benn's picture
David Benn
Offline
Joined: 2010-07-29

Thanks Matt!

I know you're a very busy person, but I will appreciate whatever contribution you can make, whether review or content.

David

Hi Ken! Long time no
David Benn's picture
David Benn
Offline
Joined: 2010-07-29

Hi Ken!

Long time no key. ;)

I would appreciate seeing what you've done with the VPHOT manual and with the image effects.

I was planning to do it all in Google Docs from the start. That's a useful caution re: loss of data. The only time I used Google Docs, I used the drag and drop or file chooser approach to image insertion.

I thought that a separate document per chapter / major section might help guard against loss and prevent the document from becoming unmanageably large.

Thanks.

David

I heard from a couple of
David Benn's picture
David Benn
Offline
Joined: 2010-07-29

I heard from a couple of people that the recent Citizen Sky DSLR photometry tutorial writing workshop made use of Google Docs (GD) also.

It would be interesting to hear more about that group's impressions of GD.

David

DSLR workshop & Google Docs
Matthew Templeton's picture
Matthew Templeton
Offline
Joined: 2010-03-12

Hi David,

I worked on the equipment chapter at the workshop and I think we mostly found it pretty useful.  The only real issue was figuring out permissions issues and ownership at the very start, but once we were all logged in and working it went ok.  As far as word processing, it's about as feature-rich as it needs to be, and can produce a decent PDF on demand.  I liked it.

Matt

Update on user manual
David Benn's picture
David Benn
Offline
Joined: 2010-07-29

I've written a first cut of the following sections in Google Docs:

  • Introduction
  • Observation sources
  • Licensing
  • References and Further Reading

With VStar 2.15.1 released, I plan to keep chipping away at this.

However, if you would like to pick up a section to write, please let me know! I will make the document available to you via Google Docs sharing.

If you use VStar, you could write a section based upon your hands-on experience. I could post a sample section here if that would help.

David

Sample user manual sections
David Benn's picture
David Benn
Offline
Joined: 2010-07-29

Hi all

I've attached some sample first-cut user manual sections.

Feel like writing a section? This is a parallelisable task.

Want to add review comments to a section like the one attached?

Just let me know and I'll provide you with access to the Google Docs area.

Comments welcome.

David

Manual
LKR's picture
LKR
Offline
Joined: 2010-09-01

Awesome! I will definitely give you feedback on these 4 pieces.

 

KL

Thanks Kristine. If you want
David Benn's picture
David Benn
Offline
Joined: 2010-07-29

Thanks Kristine. If you want me to provide access to the Google docs, let me know. Direct feedback is also welcome.

David

looking good
LKR's picture
LKR
Offline
Joined: 2010-09-01

Thanks for the access. I'm glad I was able to provide useful feedback so far and will get to work on the glossary and annotated references ASAP.

 

KL

First VStar User Manual Release
David Benn's picture
David Benn
Offline
Joined: 2010-07-29

Hi all

It gives me great pleasure to announce that the first release of the VStar User Manual is now available.

You can download it via the Big Yellow Button on the VStar Overview page, where Sara has made it available.

See also Sara Beck's post on the AAVSO page: http://www.aavso.org/vstar-user-manual

This has been a long time coming. I started this thread in April and have been writing the manual on and off since then, but I've had this manual on my mind for a long time. Just as VStar evolves, so will the manual.

For much of that time, Kristine Larsen has been reading and re-reading what I've written, providing feedback and corrections and making suggestions for additions, and challenging the content and its ease of understanding. In addition, she wrote most of the Glossary and annotated my bare bones references and further reading sections. Thank you Kristine! Having someone to bounce ideas off has been invaluable.

Thanks to Matthew Templeton for providing feedback on an early draft of the Period Analysis section.

Thanks to Sara Beck for providing feedback on the latest couple of drafts, for making the document available on the AAVSO web and for her omnipresent support.

Enjoy!

David 

Major Squee!!!
LKR's picture
LKR
Offline
Joined: 2010-09-01

It's here! it's here!  (wild Muppet flail)

So glad to have this see first light!!!!! Thanks for all your hard work, David. All AAVSO members (and others who use VStar) owe you a huge THANK YOU!


Kris Larsen

VStar User Manual
BSJ's picture
BSJ
Offline
Joined: 2010-03-12

Congratulations David!

This was a major undertaking and something that has been on our minds for a very long time.

I can't wait to use the Manual to help me make some of those neat plots you show in the Time-Frequency Analysis section. T UMi's period really is changing fast! Now when I see a light curve that looks like something funny is going on, I can use VStar to help me figure out what is happening.

Thank you!
Sara

AAVSO 49 Bay State Rd. Cambridge, MA 02138 aavso@aavso.org 617-354-0484