Welcome to the Cumulus Support forum.

Latest Cumulus MX V3 release 3.28.6 (build 3283) - 21 March 2024

Cumulus MX V4 beta test release 4.0.0 (build 4018) - 28 March 2024

Legacy Cumulus 1 release v1.9.4 (build 1099) - 28 November 2014 (a patch is available for 1.9.4 build 1099 that extends the date range of drop-down menus to 2030)

Download the Software (Cumulus MX / Cumulus 1 and other related items) from the Wiki

Volunteers Please - Cumulus MX Documentation

Please use this Forum to make suggestions for the future updates additions and general maintenance of the Wiki. Since I am sure most of these will be valid suggestions, so as they are completed in the Wiki the Topic will be deleted from this Forum, and this will act as reminder to anyone updating the Wiki of the jobs still to be done.

Moderator: HansR

Post Reply
User avatar
mcrossley
Posts: 12692
Joined: Thu 07 Jan 2010 9:44 pm
Weather Station: Davis VP2/WLL
Operating System: Bullseye Lite rPi
Location: Wilmslow, Cheshire, UK
Contact:

Volunteers Please - Cumulus MX Documentation

Post by mcrossley »

I am acutely aware that Cumulus MX is badly lacking in the documentation area. I'm busy patching bugs and adding C1 catch-up features, so do we have a small group of people who are willing to put some time into creating this?

I see two areas...
  • A manual type document, with sections on say getting started, different platforms, and the various station configs. Then further sections explaining basic setup.
  • Maybe some short videos showing the "how-to's"
Now a lot of this information is already available spread across forum posts and the Wiki. The obvious solution for me would be a new section in the Wiki, that pulls all the information together, gets rid of old redundant stuff, and presents it in logical manner.

Its a big task, but that's why I cannot do it by myself.

Over to you guys and gals.
ExperiMentor
Posts: 214
Joined: Tue 24 Nov 2015 11:30 pm
Weather Station: Fine Offset & Davis Vantage Vue
Operating System: Windows 10; Raspbian Buster
Location: Switzerland

Re: Volunteers Please - Cumulus MX Documentation

Post by ExperiMentor »

I'd be happy to give some help, but also cannot do it alone.
I'd need someone else to lead the project and advise how to get started.

Completely agree that the best use of Mark's time is the actual program development (and answering the difficzult questions the rest of us cannot ...)

Ian
prodata
Posts: 317
Joined: Sat 05 Feb 2011 7:13 pm
Weather Station: VP2
Operating System: Windows - all flavours
Location: Littleport, East Cambs, UK

Re: Volunteers Please - Cumulus MX Documentation

Post by prodata »

This is a great idea, albeit one that I don't have the expertise to contribute to myself.

But could I make a plea not to overlook the simple, obvious stuff in any webpage/documentation/video. There are many weather station users out there (not always the most expert of computer users) who are not yet familiar with CMX and might really benefit from a basic page or short video that just explains what CMX is and does; what its main features are; and is illustrated with screenshots. This doesn't need to be minutely detailed - just a summary of the main basics.

Potential users would then find it a lot easier to decide whether to explore CMX further and follow up on any more detailed instructions that may be provided separately. As far as I'm aware, there's no resource out there at present that provides a simple, accessible summary of CMX and its features. The lack of such a summary is very possibly limiting the number of users who reach the point of checking out CMX.
John Dann
Prodata Weather Systems
Littleport, East Cambs, UK
http://www.weatherstations.co.uk
sfws
Posts: 1183
Joined: Fri 27 Jul 2012 11:29 am
Weather Station: Chas O, Maplin N96FY, N25FR
Operating System: rPi 3B+ with Buster (full)

Re: Volunteers Please - Cumulus MX Documentation

Post by sfws »

A renewed call for contributors

The Cumulus Wiki has a long history of contributors starting on a big plan of creating new pages, and updating existing pages. The problem each contributor meets is that maintaining the Wiki is a massive task, especially when you have a developer continually moving the target. I have done a re-organisation of the Wiki, although it is not as complete as I would like because of the limited rights a standard user has. Each contributor has to stop sometime, and the content then gets out of date unless others contribute.

Please can several people volunteer to share the big job of working through release announcements (since June 2020) and updating pages. EDIT:Changed that from "someone" to "several people"

The Wiki is currently not friendly for newcomers who only have experience of MX. What is missing is a total redesign of the Wiki. That is a huge task, but there are people out there who have knowledge of rival weather software, who should be able to document the pros and cons of MX, and https://www.wxforum.net/index.php?board=118.0 might give some hints.

Please can several people with necessary experience share the big job of documenting features of MX not yet documented, especially relating to weather station types or sensors not supported by legacy software.
Last edited by sfws on Mon 12 Apr 2021 10:39 am, edited 1 time in total.
User avatar
saratogaWX
Posts: 1170
Joined: Wed 06 May 2009 5:02 am
Weather Station: Davis Vantage Pro Plus
Operating System: Windows 10 Professional
Location: Saratoga, CA, USA
Contact:

Re: Volunteers Please - Cumulus MX Documentation

Post by saratogaWX »

Dear sfws,

I've heard your plea above. Since you are active, involved and knowledgeable, I've added you to the Administrators group on the Wiki. You now have the power to change/reorganize as needed. Thanks for your continuing efforts to make the Cumulus Wiki a useful knowledge base.

Best regards,
Ken (hoster, admin for cumuluswiki.org)
sfws
Posts: 1183
Joined: Fri 27 Jul 2012 11:29 am
Weather Station: Chas O, Maplin N96FY, N25FR
Operating System: rPi 3B+ with Buster (full)

Re: Volunteers Please - Cumulus MX Documentation

Post by sfws »

This post might be helpful to potential contributors.
------------------------------------------------------------------------------------------------------------------------------------------
THE PLEA
If you are hesitating over where to start, then read the first two posts in this topic, or read the suggestions for contributions listed at foot of the main page of the Wiki (or notes on some other pages). You have useful knowledge, share it.

Any small contribution is a step forward.

If in your experience,
- you identified something that is not covered in the Wiki,
- found it difficult to find what you wanted to look up,
- or found something that is badly explained in the Wiki,
then you know where to start in a contribution towards the improvement.

----------------------------------------------------------------------------------------------------------------------------------------------------
THE CHALLENGE

Cumulus 1
Cumulus 1 came with help pages that Steve Loft edited for each of his releases.
The original Cumulus Wiki was built upon the structure of the Cumulus 1 software help pages, but was not written for novice users.
The original Wiki contributors (mostly David Jamieson and Steve Loft), used it to document extra detail for more technical readers. Steve was the biggest contributor of such updates to the Wiki, and he could explain how his software worked/changed. The legacy software evolved comparatively slowly with just 9 major releases, first in 2004 and last in 2014, keeping much of the functionality the same throughout, and therefore the original content of Wiki remained valid, and task of adding new content was relatively short and simple.

Changing the Wiki to cover MX was a huge challenge.
MX does not come with any documentation bar a few hints within the settings pages.
The MX beta that Steve Loft wrote was coded to be broadly similar to his legacy software, thus to start with, much of the Wiki content for the legacy software was still valid. Steve did make some changes to some pages so they did cover differences between C1 and CMX better.
Mark Crossley created a couple of new Wiki pages specifically for MX based on what Steve had posted about his beta MX in the forum, but he did not update these MX specific pages when he took over MX development, despite the fact those pages no longer matched the new MX.
David Jamieson began marking content so it was clearer what applied to C1 and MX, but that too was abandoned.
--------------------------------------------------------------------------------------------------------------------------------------------------
MY CONTRIBUTIONS
You can choose to skip the rest of this post; however I have included it for three main reasons:
First, I discovered the hard way that creating a brand new structure that I understand (and restricting what is covered on one page) is better than adding new text to a design structure created by someone else; I hope you as a future contributor are not constrained, but (aided by what I have started) you realise that lots of small new pages are the way forward!
Second, in my early contributions I had a lot of problems because I was forced to fit in with existing pages that as a normal user I had no access to; since I was given admin rights I have done a lot to make it easier for normal users to contribute to Wiki, and so read on if you as a future contributor wish to understand how I have made life easier for you!
Third, I have realised that taking responsibility for documenting MX is extremely hard, and I document why below; therefore I have clearly indicated lots of opportunities for others to contribute.

(The majority of my edits are done by taking a copy of an entire Wiki page, editing it offline, deleting original content, and then pasting back my new text usually divided between original page and several new pages. Working offline makes it harder to get heading levels, and links correct; so you may see that I have made several subsequent edits just to get those right. There can also be issues if someone else does an edit while I am splitting the page offline, as by incorporating their work on the appropriate page in my new design before I paste means their edit is thereafter incorrectly attributed to me!

Most of my edits for Cumulus 1 were taking words by Steve Loft (and others) either from forum posts or from the (public viewable) enhancement database; and repeating that text (with minimal editing) on the most appropriate of the Wiki pages created by David Jamieson.
Therefore very little of what I typed in for cumulus 1 needed me to choose the words or phrases. Wiki pages grew dramatically because although I found text written by others I could add, I seldom deleted/rewrote what already existed, arguing it remained valid.

When I moved from Cumulus 1 to MX, I realised that the Wiki was of little use to MX users. What had been written either for C1 or specifically for MX was now out of date given how much Mark had changed MX from the Steve Loft beta.
My early edits for MX were initially restricted to attempting to update Wiki amendments started, and then abandoned, by Steve Loft, David Jamieson, or Mark Crossley.
My attempts to document MX faced multiple obstacles:
1 - Restructuring the content, to make the Wiki friendlier/easier to use, the problem here is that there is a lot to restructure!
2 - Previous contributors frequently started and then abandoned some change, but did not leave notes regarding planned content, so I had no idea what they had intended when they abandoned editing
3 - Creating Wiki content for anything not yet covered. The problem here is that I only use the most tiny proportion of MX functionality with my very old weather station, and so I never had enough knowledge to plug the gaps in what the Wiki covers.
4 - Another obstacle is that neither the release announcements, nor any forum posts, explain enough about how MX works to act as source for any documentation. This makes documenting MX extremely difficult and so it consumes a lot of my time in research before any text can appear in the Wiki.
5 - MX changes at a rapid pace, so anything typed into Wiki quickly becomes wrong (see below)

Mark Crossley first tweaked MX in December 2018, but he has (as at 3 years later) produced around 16 major releases (and they really do make drastic changes), and probably thousands of minor code commits, adding a huge amount of extra functionality but also often taking MX further and further away from earlier MX releases, also it is now very unlike the legacy software.
The consequence for me was that almost all my Wiki work related to MX became out of date as soon as I completed it. Current readers will not realise that the majority of what I have input re MX has been subsequently deleted. It is difficult to remain committed to any task where your previous contributions (that took so much of your time to do) so quickly becomes worthless! (From now on, I will focus on updating just a very small selection of pages, hoping others will take over most of the chore of Wiki updating).

People have commented that many Wiki pages are difficult to read and yet they don't get involved in making it better. For the record, this is how I have tried to improve the Wiki:
1) Ken and I have reorganised the "Main Page" adding a new MX column, and providing links to other pages that explain how to read and edit the Wiki. Some key pages (like "Software" and "Main Page") remain locked (so you need admin rights to edit them) because of the importance of accuracy of their content, but I have unlocked some of the other pages that I could not update before I got admin rights, and future contributors will benefit from these control changes.
2) I have locked a number of pages that are only for Cumulus 1, so they do not accidentally get replaced by MX specific content. Although pages that cover both legacy and MX flavours of Cumulus are complicated, I have left them unlocked and hope a future contributor might want to split each of them into separate pages for each flavour.
3) I have made a start on the huge task of replacing existing long pages in the Wiki with multiple small pages. This means that a lot of material is on different pages to where it might previously have been found. Sometimes I have retained old page names, but normally I have devised new naming.
4) I have therefore started the move away from the page naming structure that David Jamieson created based on the Cumulus 1 help file. I hope that by putting some material under Cumulus folder (e.g. Report folder) and file names (e.g. month.ini), and other material under names related to task being done (e.g. correcting extreme records), and by making improvements to the Category system initiated by David, that I have perhaps made it easier for future contributors. Future Wiki contributors can link whatever new pages they create to any relevant category pages, and they can edit the category pages without admin rights; in other words future changes to the structure will be easier for new contributors.
5) To make it easier for readers to pick just the relevant paragraphs on any redesigned pages, and to navigate more quickly between pages, I have added loads more sub-headings and links. I have done this on pages written by other contributors, as well as with pages I have totally rewritten. I hope future contributors will continue to consider multiple headings and cross-referencing links, because it does make life easier for Wiki readers.
6) I can't change some Wiki functionality, the "Replace Text" functionality (a global editor) that has been so useful to me since I got admin rights continues to be unavailable to any contributor without those additional rights.
7) The Wiki continues to be weak on helping novice readers, and it really needs a further reorganise into simple guides on separate pages to the more technical reference. I don't have time to do that, but I intend to gradually separate out information useful to novices from the more technical detail, on some individual pages, that might make it easier for another contributor to pursue the production of documentation aimed at novices.
Post Reply