User Documentation

Hello Document Writers

As LibreCAD 2.2.0-RC1 moves towards release I've started writing guides and tool descriptions.  I've only posted a couple of pages so far, but as it has been pointed out elsewhere in the forums, the are a number of manuals, guides, and tutorials posted throughout the wiki, unfortunately many are out of date.  While I've started writing a couple of things, in the back of my head I'm always thinking 'Where should this go to make is easy to find for (new) users?', "What topics/format/etc should be used?", and many other questions that relate to writing documentation for LibreCAD.

There are other areas in the forum, notably “Tutorials / Manual topics”, that discuss many items related to user documentation that will useful for writing up-to-date and relevant documents.  Some of these can be adopted or integrated into new pages, but in a structured way that would allow users to navigate the documentation, but a good starting point would be helpful.

LoB (Lord of Bikes) has created this sub-forum to allow us as documentation writers to discuss topics related to documentation.  For those that are wanting to contribute to LibreCAD's documentation, I'd like to invite comments, ideas, and even submissions.

Many thanks Gary for drum up business

I've been recently informed about this blog post:
https://www.divio.com/blog/documentation/
Very interesting reading about 4 basic types of documentation, maybe this helps us too.
Maybe nothing new, for the advanced documentation writer, but surely valuable for less documentation-prone developer

My vision for a navigable, searchable documentation is https://readthedocs.io/
They provide free hosting for open source projects, are well connected with github, our source code provider and support different offline output formats.
Beside the online version we can automatically create PDF or eBook for example. And all of this for different versions!

They use a documentation generator, called Sphinx, which uses an advanced markup language.
The markup language is one of the issues I see, it is more complex than the wiki syntax and may scare potential writers.
Also the documentation source will be kept on github, as this will provide versioning and auto build capabilities.

Possibly we can steer a middle course. Writers can still use the wiki to write individual sections if they don't want to battle with Sphinx or github.
Then advanced members can port the wiki articles to the Sphinx source.
But this will need some guidance I think, to avoid waste of efforts and smooth syncing.

I recommend to create a new wiki section to collect the ideas for structure and types of documentation.
I can link this wiki section in the sub forum head line for easy locating.

Armin

Thanks for the links.  I looked quickly at the divio blog and I agree  it will be helpful.  It puts some definitions around my thoughts in terms of manual vs guides vs etc.  Good direction...

I also like the idea of something beyond the wiki. There are a number of posts from people looking for off-line documentation.  Having a good CMS for the documentation is a great step forward.

I've created a 'landing page' on the wiki [ LibreCAD User Documentation (v2.2.x) ] that I'm just going to start building out from and consolidating some of the other stuff (yup, a technical term) that I find.  Lots of the documentation will be new, but as I read through the forums and find other postings on the wiki - I'm going to borrow it blatantly..


Cheers,
Gary


PS: After trying IRC, given the time difference -  exchanging emails, as needed, will be a better alternative...

I've put the wiki link to the sub forum header.

The link in your post doesn't work, because of the closing parenthesis. It links to an empty page.
You can edit your post and use the Link button to fix this, to avoid any confusion.
With the link button you can apply the correct URL and add a replacement text for a working link. I did so in the sub forum header.

For the tutorial part I tried to rework
https://wiki.librecad.org/index.php?title=Starting_to_draw
a bit and would like to get feedback on this.

Since I am a totally Newbie I thought I'd still be in the right "mindset" and stupid enough to
not understand how things are supposed to work.

Hallo Wolfgang, der Einfachheit halber in Deutsch:
Ich würde vermeiden Rechenwerte einzusetzen, wenn irgendwie möglich, es sei denn sie sind genau. Bei solchen trigonometrischen Berechnungen wird der Ausgabewert ja meistens gerundet, und beim Wiedereinsetzen in LibreCAD hast du auch nur begrenzte Stellen. Es schleichen sich also Ungenaugkeiten ein. Im wahren Objekt mag das unerheblich sein, beim CAD-Zeichnen kommt man damit aber in Teufel's Küche. Also möglichst geometrisch lösen. Zumindestens in einem Lehrbeispiel sollte alles korrekt sein. Nicht schon gleich mit Schludern anfangen.
So wie du es gezeichnet hast ist der Obergurt weniger als 40mm hoch und die Verbindungsstäbe nicht rechtwinklig zu diesem.
Im meiner modifizierten Version habe ich Parallelen in den entsprechenden Abständen zum Obergurt als Hilfskonstruktion angelegt und dann Lotrechte darauf durch die Schnittpunkte mit dem Untergurt gezeichnet.  carporteast_mod.dxf


Nicht übel nehmen

dellus

Ergänzend noch: die Verwendung von Polylinien in LC ist oft problematisch, weil sie auf Befehle wie Trimmen  oder Fangschnittpunkte gar nicht reagieren. Man muß sie immer erst zerlegen. Deshalb vermeide ich es sie überhaupt zu verwenden.

dellus

Berichtigung: das mit Fangschnittpunkten stimmt nicht, da hatte ich wohl "snap on entity" an.

Hi Wolfgang,
I followed your re-working using the command line ok and think in general it is excellent. However I am not sure about constructing the beams with the mouse. I think it is necessary to click on 4 points, not 3, before closing the beam outline. As you suggest it is not really necessary to be precise about point placement but it is useful to do so, and, using the mouse does make it difficult to construct the beams with parallel sides but it does give the person using the exercise some practice at using the mouse.
I also interspersed extending the beams to meet the top of the frame using the mouse to drag the top two corners after the outline was created and using Snap on Entity to make the points attach to the top of the frame




Otherwise I think the additions you made are fine.

The links in the forum header on the main page are really useful. How about moving the Source Code link from first to third?