How to Contribute

The documentation for LibreCAD will ultimately end up in a GitHub repository where it can be maintained and updated as new versions of the application are released.

There are several paths that the will lead to the documentation on GitHub, but generally it starts with a submission from anyone who wants to contribute.  Submissions can be via the forum, as a post (or as an email), directly to the wiki, or even via GitHub – what ever is the easiest for the contributor.

Eventually all relevant submissions be taken from the wiki and copied into the user documentation ‘source code’ that will be hosted on GitHub.  Documents hosted on GitHub uses GitHub’s own formatting (markup language), so any submissions from the forum or wiki will need to be modified by the maintainers as it is incorporated into the documentation source.  As the documentation will need to be edited by the maintainers, extensive formatting of a submission should be avoided.

To help with the organization of the user documentation, a ‘landing page’ has been created on the wiki.  The link to the landing page can be found in the sub-forum’s head line.  The landing page is the outline for the “LibreCAD User Documentation” with the proposed sections and links to related pages.  The wiki is very much a live documentation and will be changing as the wiki is added to, modified, etc.

See the LibreCAD Manual Wiki for more information.

The user documentation will require some standards to provide a consistent structure, style, format, and appearance.  Some of that will be driven by what is available in GitHub’s markup language (called “Markdown”), but other things to consider will be how to incorporate images, tables, etc.  Watch here for further discussions on the standards as they develop.

See the LibreCAD Manual Wiki for more information.

Does what you are proposing mean that most documentation will require double-handling?

I haven't tried it but Pandoc claims to convert between a range of document formats including markup formats. Has anyone looked into this possibility?

Initially, yes there will be some double-handling until everything is moved over to GitHub.  Once eveything has been moved to GitHub the documents can be versiomed / forked /updated / revised with each release - hopefully easier than trying to maintain it on the wiki.

I'll have a look at Pandoc.  Right now I just copy & paste and then updated the source files for the documentation with the appropriate markup (markdown or reStructuredText) with some search & replace.  I'm collecting materials from a variety of sources; the wiki, the forum, source code and my own documentation.  I've been using the wiki landing page as a starting point for the documentation layout and content.  Much of it needs to be updated and/or expanded on.

I'll have to go back and look and see if I've mentioned this, but the intent is for new contributions (via the forum or the wiki) to be as simple as possible, i.e. plain text, and then the formating done in the GitHub document source.

Utimately the end-user documentation will be hosted on readthedocs.io as html, pdf or epub documents.  Each format is generated from the source as required.  readthedocs.io hooks into Gitb, so the documents get updated automatically.  I've been using my own repositry to

I've setup the github repo at https://github.com/LibreCAD/docs
and hooked it to a LibreCAD account at readthedocs.io

The HTML docs are available at https://librecad.readthedocs.io/en/latest/

The repo contains only, what sphinx-quickstart has produced. This is a starting point only and we can now apply a template, structure and docs.

@Gary_S, when you have a github account and feel safe in dealing with git/github, we can consider write permission for you. The other option is the pull request way, which will work anyhow.

@ubiquitous, hopefully not most docs will need double-handling.
Our fear is, to scare off authors who are not versatile with git/github or sphinx.
Preferably contributors will have experience with the docs tool chain and contribute with pull requests on github.
Only for those who are not, the wiki should be the place to contribute. Experienced contributors can maintain this and carry over the wiki docs to github.

Armin

LordOfBikes wrote

I've setup the github repo at https://github.com/LibreCAD/docs and hooked it to a LibreCAD account at readthedocs.io

The HTML docs are available at https://librecad.readthedocs.io/en/latest/

Good timing - I was just going to ask you for that  

I found the GitHub repository and created a fork.  I've been working with the tool chain (local repository -> GitHub fork of LibreCAD docs -> RtD LibreCAD Docs (Dev) and have the environment working nicely.  Because I already have a fork, let's leave it that way (for the time being).  It offers the advantage of a dev/test environment to build the docs and try different approaches prior to commiting anything to the end-user environment.

Hit the RtD link above to see the latest iteration...

Gary S

Sorry it is not clear to me. I suggest that you make 2 lists :
1/ by order of simplicity the possible ways to contribute (from novice contributor to expert)
2/ same list by order of ease for developer (from expert to novice).
After I guess that every one will be able to pick the most efficient way to contribute. Thank you and apologises for the extra work  

If I understand you correctly...

In order of difficulty:
     - simple text via the forum or email (easiest)
     - via the wiki (supports images and some layout)
     - restructuredtext via github (difficult - need to know git, github, markup language (restructuredtext), the documentation and writing standards (*)

I'm not sure what you are asking for in #2.

*: I have been negligent in posting the standards as I have been developing them as I've been writing, so I will update the initial post in the subforum.

I've sent invitations to both of you to join the new created LibreCAD/Authors team on github.
As a team member you have permission to edit the repositories wiki:
https://github.com/LibreCAD/docs/wiki

As fa201 proposed, I agree to fill this wiki with related content, like documentation and writing standards or useful links for contributors willing to work with restructuredtext via github.
This keeps too technical information out of the forum and concentrate things on a single place.
We can link to this wiki from the forum for interested contributors.

I also suggest to use the new created Zulip stream Documentation and Wiki, where we are all subscribed to, to discuss wiki arrangement and other LibreCAD/docs concerns.

Armin

2/ was the easiest way for developers to include the contributions so I guess it is :
- restructuredtext via github (easier to developers)
- via the wiki (supports images and some layout)
- simple text via the forum or email (less easy to developer).

Regarding the standards, it will be helpful. I will try to contribute with Github but I am not yet ready with restructuredtext. Thanks.