-
-
Notifications
You must be signed in to change notification settings - Fork 22
Home
This wiki provides information to individuals that want to contribute to LibreCAD's User Manual (maintained on GitHub, hosted on Read the Docs). The User Manual is focused on the features and functions of LibreCAD, and end-user operations.
Additional user documentation can be found on the LibreCAD wiki; Tutorials, parts libraries, etc. and developers' wiki; tools, coding standards, compiling instructions, etc.
Read the Docs (RtD) provides free hosting for open source projects, is well connected with GitHub (our source code provider) and supports different offline formats. In addition to the online version we can automatically create PDF or eBook for example. And all of this for different versions!
RtD uses a documentation generator, called Sphinx, which uses an advanced markup language (restructuredtext - See the Resources page). The environment may seem daunting, but there are a variety of ways to contrbute without having to understand the environment or learn a new markup language.
There are a few ways to contribute to the LibreCAD Manual, in order of difficulty:
- simple text via the forum or email (Easiest - leave it to the authors / editors to sort out the formating and integration.)
- via the wiki (Intermediate - supports images and some layout. Leave it to the authors / editors to sort out the formating and integration.)
- restructuredtext via Github (Difficult - need to know git, GitHub, markup language (restructuredtext), the documentation and writing standards.)
- Submitting an "Issues" request via GitHub.
There are different types of documentation (see the Resources page for more details). The LibreCAD User Manual consists of:
- Explanation (About, Appendices)
- How-to guides (Getting Started, User Guides)
- Reference
Tutorials are not included in the User Manual, but are available on the LibreCAD wiki.
There are a few things that need to be kept in mind when writing user manuals. There are many resources available on the web that will provide more information, but some of the common themes that appear often are:
- Use "active voice"
- Establish standards
- Write clear instructions for a user
- Be detailed, but also brief and concise
Also one more thing to keep in mind - the manual is for LibreCAD. There are many related topics, such as drafting (draughting), architecture, etc. It is always tempting to add additional subjects for a greater understanding, but the manual provides the information on how to apply the tool to the task, and not the task itself. Essentially, a line needs to be drawn (no pun intended) to keep the manual manageable and relevant.
More information and resources are provided in the section shown on the right.