How to Contribute

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

How to Contribute

Gary S
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.
Reply | Threaded
Open this post in threaded view
|

Documentation Standards

Gary S
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.
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Standards

ubiquitous
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?
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Standards

Gary S
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
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Standards

LordOfBikes
Administrator
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
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Standards

Gary S
This post was updated on .
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