Re: commands missing

dxli wrote

I know it's not the best way of documentation...

No, it's pretty poor and should be improved: https://forum.librecad.org/Self-Documenting-Tools-tp5725976p5728021.html

I also think the code should contain a single full command with the alternatives given in the alias file.

I am not clear on the current status of our documention.

Our wiki is current locked and outdated;
To include docs within the source code would introduce too many code commits;
Should we use the github.com wiki? Looks like we start to get github spam also;


Somewhat related: we also got spam at this forum, should we enable some spam detection on this forum? or simply skip email sending for first time forum users?

flywire wrote

dxli wrote

I know it's not the best way of documentation...

No, it's pretty poor and should be improved: https://forum.librecad.org/Self-Documenting-Tools-tp5725976p5728021.html

I also think the code should contain a single full command with the alternatives given in the alias file.

Hmm, we need more communication within the community to reduce misunderstanding. I'll leave @LordOfBikes to respond to some of these.

dxli wrote

I am not clear on the current status of our documentation.

GnuCash development is a team effort. The developers support each other, review changes, and share what they know. That teamwork makes a huge difference, if someone leaves or takes a break, others can step in and keep things moving smoothly.

The current User Manual, by contrast, took a very different route. It was almost entirely a solo effort by one very dedicated contributor who did an excellent job, but there wasn’t a team built around it for ongoing updates. So when they stepped back, there was no established group to continue maintaining and updating the documentation.

dxli wrote

To include docs within the source code would introduce too many code commits;

I disagree. The LibreCAD documentation (Manual Content) shows how this can work effectively. It follows the Diátaxis framework, separating material into tutorials, how-to guides, reference, and explanations. Only the reference really needs to stay tightly in sync with code updates.

The current reference documentation is largely made up of tables with explanatory text (for example, tools.rst). Conveniently, all the detailed information for the reference tables already exists within the code itself.

I suggest:
* Change the manual format from reStructuredText to Markdown for better GitHub compatibility and easier editing.
* Tweak the structure so tables can be updated separately from explanatory text.
* Add a process in the code to automatically generate the table(s).
* Occasionally update the explanatory text as needed.

I could take on the reference docs, with code support from the development team and help managing version control through Read the Docs. There’s a lot of good material already in the GitHub repo that would fit well into the other parts of the User Manual.

Thanks @flywire for the kind reminder.

This went way off topic and does not answer @Methusalem's question at all.

Anyhow, this forum will be closed soon, thus I add my two cents anyway.

We have https://github.com/LibreCAD/docs/ just for this, which is published under https://docs.librecad.org/. But there are authors missing to continue the work.
@flywire is right, that this is also a matter of communication. It is cumbersome for authors to dig through source code and git logs to elaborate changes and how new features work.
The coders are responsible to provide at least a brief summery in of their work as a base for the authors.
Authors are not necessarily able to read and understand source code. Let alone, that end users can get any value out of source code.

The docs repo is prepared to continue the work for changes in the master branch. Release 2.2.0 is fixed and will be available in its current state when changes are applied.

The reStructuredText format was selected with the intention to provide multiple formats, online HTML, printable PDF and others. Also it is a good base if somebody will start translating.
Github compatibility is no requirement for user documentation.

We used Doxygen once and there are for sure still remains in the source code. This could be a good interface between coders and authors.
Coders put special formatted comments in their code which can be published as HTML reference by CI or automated on our server.
But this needs some discipline from coders and is an obstacle for fresh contributors. It also requires more quality assurance on pull requests. Which might on the other hand scare off new inexperienced contributors.

The Github wiki was never intended for user documentation. It should be used for developer related content, probably for beta tester instructions too, but never end user documentation.

Our Wiki at https://dokuwiki.librecad.org is not locked, just the registration process is disabled for spam protection. There are frequently requests for new accounts, which I create, but they never started contributing.
I suppose they don't understand or read instructions carefully. They think an account is needed to get information or using the software.
The old Wiki from https://wiki.librecad.org/ is disabled because it runs on an outdated MediaWiki. A few hours after going online it is targeted by massive DDoS attacks which overload our server.
@flywire already replaced some important links in the new Wiki to the Wayback internet achive. Great idea, many thanks!

The forum, as mentioned above, is about to become read only soon. Nabble, the forum hoster is outdated and offers no spam protection at all.
This forum will stay online for a while to keep the knowledge, read only will stop the spam.
As replacement I have nearly finished the work on our self hosted Discourse forum.
It is way more modern, with many cool features and above all lots of spam protect mechanisms.
It also has a chat feature, which allows us to shut down our Zulip channel and merge two services into one.

Hopefully this will become a more comfortable place to improve communication.

LordOfBikes wrote

The reStructuredText format was selected with the intention to provide multiple formats, online HTML, printable PDF and others. Also it is a good base if somebody will start translating.
Github compatibility is no requirement for user documentation.

reStructuredText doesn’t seem to offer any advantage over Markdown for this project. Both can generate HTML, PDF, and localisation workflows with the right tools (subject to testing), but contributors clearly favour Markdown based on existing repo activity.

That said, the real issue isn’t the syntax; it’s that there hasn’t been a proper community discussion about the documentation goals and workflow. Once there’s agreement on that, the format will sort itself out naturally.