Future Versions of Sharpcap

[admin]

Thanks all for the feedback. I think I will probably 'bite the bullet' and work on updating the documentation before the end of the year (note that I am deliberately not saying whether I intend to finish by the end of the year or just start by then!)

cheres,

Robin

[Hibou]

I agree with Calan I only use documentation when I have a problem, and even then, I first Google for mentions of similar problems, and experiment to find a solution. If searching fails, I post my problem on the forum, and usually get helpful suggestions, and often solutions. The user interface is more important than the documentation. For beginners it should be as simple as possible, and intuitive to use. More powerful features should be revealed as the need arises, with experience.

There is of course the usual problem of feature creep, and eventually a new version should aim at restoring initial simplicity, and rationalising the introduction of more complex features.

Just my personal opinion. Different people have different approaches.

[calan]

Just to be clear... as a software developer since the late 80's, I understand the need for good documentation from a business standpoint.

My comment was mostly tongue-in-cheek (hence the smileys), but with that said... I don't mind new features being added without full documentation.

Astro software is a different animal. This isn't some mainstream Micro$oft program being pushed out to 3 billion users. These forums and the tight astro community are the user manual for most of this stuff.

The fact that SC is as feature rich and well documented as it is, in whatever version it is currently sitting at, is frankly quite astounding.

[Toshihito Watanabe]

In my opinion... The development of new features is a good thing, and users will use the documentation to understand them first, including existing features, but only if they are consistent with the SC.



Watanabe

[Hibou]

Other people could help with documentation, as David Richards and Toshihito Watanabe already have. In fact, users might be better at seeing what needs more explanation. I could imagine assigning web-based chapters to particular users, with Robin correcting where necessary. A complete reference manual is a big job for one person.

[turfpit]

Hibou

Other people could help with documentation, as David Richards and Toshihito Watanabe already have

When I embarked on the documentation project it coincided with the implementation of the SharpCap Forum back in 2017. At the time, there was no written manual and Sharpcap support was scattered across various forums based out of the UK and USA - which meant no central pool of information. There is no doubt in my mind that the creation of the manual and the forum did help in providing a centralised and managed knowledge base.

A complete reference manual is a big job for one person

Agreed.

I worked on the 2.9 version of the manual, https://docs.sharpcap.co.uk/2.9/, for 8 solid weeks as a job - from February - April 2017. I was retired which did help. My work background was in data centre computing (server management) - mainly in heavily regulated industries such as pharmaceutical manufacturing and water utility, both of which required extensive documentation of computer systems. The hard part was I was just starting up the hobby and in effect had zero astro-imaging knowledge. Robin worked on implementing the Forum, I embarked on writing the manual. First the document structure was created as a table of contents, sections and sub-sections then fleshed out. The darker clear nights were spent acquiring images of captures in progress to add to the manual. Robin frequently reviewed the manual and answered any questions I had. The manual development was a good example of collaborative development using the Track Changes facility in Microsoft Word. One of the design goals was to try to pre-empt forum questions and provide the answers in the manual - this would reduce the support demands in the forum.

This is what the manual 'under construction' looked like:

SC docs under construction (2).JPG (103.53 KiB) Viewed 1163 times

The reality is that if I had been paid at the commercial rate for my time, then the cost of the manual would be of the order of £10,000 - 8 weeks @ £1,000 per week plus £2,000 for the imaging which took place at the bottom of my garden. I did end up with a lifetime license for SharpCap - thanks Robin. Commercially, manual maintenance needs to be factored in and balanced against the cost of a SharpCap licence.

How does adding a new feature impact the manual? A new feature usually means a new menu item is added either at the top level of the menu system or as an item in one of the menu drop-downs. Screen images of the feature in use need to be captured in the field. There may be in-document links that need to be adjusted and some testing of the manual to ensure the changes have not broken the documentation.

From version 2.9 -> 4.0, the SharpCap manual has increased from 157 to 311 pages. Robin has added 154 pages, doubling the size of the original documentation.

Perhaps now is the time to consider if a monolithic manual is the best solution for a program under continuous development? If the manual was broken up into a core manual plus sub-manuals, then adding new feature X would entail creating a sub document X. This would facilitate adding new features plus appropriate documentation. It would be in Robin's interest (encourage him) to provide the doc for the new feature otherwise he takes the hit in Forum support time. The core manual would be all the information that doesn't really change - e.g. descriptions of file types, installation, cameras. Maybe a front end with hyperlinks to sub documents delivered either as web based or a downloadable ZIP file?

Just my thoughts on this which might generate some discussion or better ideas. Hopefully the above will give Forum Users some insight into the work (other than program development) which goes on in the background.

[Edit] Moving from the monolithic document may ease documentation maintenance and document translation.

Dave

[Toshihito Watanabe]

It is certainly a tough job for Robin to do alone, I've felt it from my own experience of translating and editing texts.

However, I think it is difficult because we are trying to get all the updated parts of the document done at once, and we should have done the corrective work each time.

Again, why not assign another staff member if possible?




Watanabe

[Hibou]

I am certainly impressed with the manual as it is, and think that David has underestimated the cost of producing it commercially - he and Robin should add taxes, social security payments, overheads etc. And I doubt that Robin has "another staff member" that he can put on it, or that it is even commercially viable to produce other than as a labour of love.

Splitting it up into a core manual of the essentials plus specialised sections might be the way to go, and is consistent with the idea of users being responsible for updating individual parts without too much supervision from Robin.

[turfpit]

Hibou

think that David has underestimated the cost of producing it commercially

Correct. I only costed my wages just give people an idea of what was actually involved timewise in creating the manual.

Dave

[admin]

Hi folks,

I am not intending to add staff for this (or other purposes) at the moment. One of the issues with that approach is that unless you can somehow find an expert in astro-imaging, imaging theory and SharpCap use then you have a massive knowledge transfer mountain for them to climb before they can write a page of documentation.

I will point out that a lot of the content that will be added to the user manual already exists - every time I add a new feature I try to write a fairly long forum post outlining how it works and how to use it - that will form the basis (with a bit of editing) of the new sections of the documentation. If you want to learn about a major feature that is not in the user manual yet, then find the 'Robin announces feature X' thread and read through it

cheers,

Robin