Documentation overhaul

[Orion Pobursky]

I'm starting an overhaul of our documentation. Since my time is limited, this will not be a short process.

I have a couple of goals:
- Convert all the documentation from its current dependency on a specific component style library to GitHub Flavored Markdown (GFM)
- Streamline the current library standards into some more beginner friendly.

I've started a new GitHub repo for our documentation so that we can have better revision history and tracking.

Here's a preview:
https://library.ldraw.org/documentation/3

Note, the above is a very rough first go. My thought process is to have all the requirements highlighted. Right now that's in bold but that style is easily changed if someone have a better idea.

As always, I welcome any and all feedback.

[Peter Blomberg]

When I started with LDRaw about one year ago, I read the docs and found them wanting. Sure, basic principles are in there, but there is nothing like a learning path to follow. I quickly found out that an immense amount of conventions are undocumented. Eventually, I learned by reading reviewers' comments and suggestions, but that is a slow way to go and subjective.

It would be helpful to have a 'tutorial' where the reader learns about the docs through examples.

When it comes to developing the documentation in terms of content, I would prefer some way of benefiting from the community. Many authors and administrators have created their own 'guidelines'. There may be e.g. alternative ways of describing/teaching T-junctions and when they need to be removed. "A T-junction on a hard edge is permitted (in some cases), but T-junctions in the middle of a surface is not (rarely ever if they can be avoided without creating long narrow triangles)". Understanding such 'fluid' rules would require many examples.

When it comes to primitives, I wish there was some way of automatically creating the primitive reference since the current listing is inaccurate. I often find more primitives in the /p folder than in the reference list. The primitive reference could also be expanded to useful subparts, many of which are known only to particular authors and reviewers.

May sound superfluous, but integrating some aspects of using the LDPE tool could benefit a beginner.

Please let us know how to contribute

[Orion Pobursky]

I 100% agree that we need more informal tutorials about parts authoring.

If you, or anyone else, are willing to write them, create a wiki account and then email me so I can approve you.

[Willy Tschager]

When it comes to primitives, I wish there was some way of automatically creating the primitive reference since the current listing is inaccurate. I often find more primitives in the /p folder than in the reference list. The primitive reference could also be expanded to useful subparts, many of which are known only to particular authors and reviewers.

The updated prim ref should actually be exhaustive: https://wiki.ldraw.org/wiki/Primitives_Reference

Feel free to list what is missing.

w.

[Peter Blomberg]

The updated prim ref should actually be exhaustive: https://wiki.ldraw.org/wiki/Primitives_Reference

Feel free to list what is missing.

w.

Please have a look at the tangs. I see one too many 8-prims and 4 too few 48-prims listed.

[Willy Tschager]

Please have a look at the tangs. I see one too many 8-prims and 4 too few 48-prims listed.

Corrected.

w.