I suggest outsourcing the CalculiX User’s Manual source to a GitHub repository. Then, the community could be leveraged to enhance it via Pull Requests.
I understand that documentation can be a tedious and never-ending work. This and the fact that many users are (proof-)reading it (because it essential to the users) make it a perfect candidate for community suggestions.
It is a very good user’s manual already! It is suited for both CalculiX-beginners as well as advanced users, comprehensive and well-written. But for example, there are quite a few typos, both minor and major (such as wrong signs of variables). Also, in my opinion there are improvements to be made concerning the link to examples, the repetitive descriptions of the different solvers for different analysis types, etc.
The idea is good but the problem is that the devs likely don’t want to spend time reviewing PRs on GitHub. The situation is similar with the solver itself - we report bugs here but many of them seem to go unnoticed and it would be great to have the possibility to report them directly on GitHub (after discussing here) with responses from the devs. But again - someone would have to maintain such repository. Currently, GitHub is used only as archive for ccx releases: https://github.com/Dhondtguido/CalculiXarchive
I agree with you @Calc_em - Many bug reports go unnoticed. I’m not sure what is the best way to support the development team, but certainly, GitHub is a great candidate for this work.
Examples of files for CCX and CGX for the benefit of other users as @mkraska did.
Examples of configuration files (.cgx for examples) or make files if it is relevant.
Links to other tools/sites relevant for Calculix (Pastix, Windows build, etc.)
Gather issues for both documentation and code for CCX and CGX. This would allow a tracking for the users without duplicating topics nor searching on the whole discourse posts, asking for new features, proposing improvements on documentations. The management of issues would be supported with tags for CCX and CGX, code, documentation, new feature, etc. This would allow Klaus and Guido to filter easily by topics. The purpose it not to add work on their side…
Discourse would remain the forum for discussion for improvement, support to users, etc. and this repository (Github, Gitlab or similar) would be a (better ?) channel to communicate for improvements for both codes and documentations.
Yes, that would be great. Exemplary file sections could become a bit messy if not limited and standardized somehow. But issues sections would be crucial. Issue management works really well on GitHub. I will be glad to help with that.
A few days ago, I’ve sent an e-mail to Dr Dhondt to share the file triggering a bug in distributing coupling but I’ve also mentioned other topics, including this potential GitHub repository for issues. I’ll let you know if I get the reply.
I know, the development of CCX and CGX is not open to public contributions as gitXXX platforms.
The idea of the repository for documentation is an improvement of current process : sending emails, posts in YahooGroup (before), posts in Discourse (now). Posts are not structured, it may not be easy to scroll and filter through dozens of posts and many users can make the same suggestions without noticing. If there is a dedicated repository, I assume it will be easier but I cannot speak for the developers.
I plan to create a CalculiXSource and a CalculiXDoc repository in the coming weeks. These will contain the daily changes I make to both the source and the documentation. CalculiXTest may follow.
Great decision, I also can’t wait to contribute to issue reports section which will be important part of these repositories (especially the one for ccx source).
Dear all, I maintain CalculiX organization on the GitHub. And famous Martin Kraska is among the members. If you’d like to join - please, let me know by private message. I need your GitHub user name to send the invitation.
Dear Guido, I was waiting for you to start using GitHub since 2018. Great decision! It will drastically increase the speed and quality of the development process. By the way, it would be much better, if you create repos for CalculiX sources and documentation directly in the organization:
And, please, use shorter URLs, for example:
github.com/calculix/ccx
github.com/calculix/cgx
github.com/calculix/doc
github.com/calculix/tests
etc.
I am not sure now where to post the typos in the documentation. In documentation 2.20 on page 402 the example should contain the required parameter TYPE, which is currently missing.
Guido recently created a new repository for source code where we can report bugs in the solver. He said that the repository for documentation will follow: CalculiX source code repository - #3 by dhondt
I am not sure the documentation repository has been created but this is just to point out that in the ccx 2.21 documentation ( USER’S MANUAL) some material, including the bibliography, seems to be missing from the table of contents. I guess adding hyperref at latex compilation would help with hyperlinks.