LDraw.org Discussion Forums
Documentation Fragmentation - Printable Version

+- LDraw.org Discussion Forums (https://forums.ldraw.org)
+-- Forum: General (https://forums.ldraw.org/forum-12.html)
+--- Forum: Official File Specifications/Standards (https://forums.ldraw.org/forum-32.html)
+--- Thread: Documentation Fragmentation (/thread-24047.html)



Documentation Fragmentation - Orion Pobursky - 2020-05-20

I'm starting to think we have a documentation fragmentation problem. There are simply too many places to look for requirements, especially for parts authoring. What I'm not sure about is if this is a presentation problem or that we need to start consolidating documents. Thoughts?


RE: Documentation Fragmentation - Travis Cobbs - 2020-05-21

(2020-05-20, 20:43)Orion Pobursky Wrote: I'm starting to think we have a documentation fragmentation problem. There are simply too many places to look for requirements, especially for parts authoring. What I'm not sure about is if this is a presentation problem or that we need to start consolidating documents. Thoughts?

Aren't they already all grouped together in the "Official Library Standards" section here?

https://www.ldraw.org/article/292

If there are other requirement documents for official parts, then I feel they should be moved into that section. In theory, all of the documents in that section could be combined into one big document (with a hyperlinked index). I'm not sure if that would be an improvement or not, though.


RE: Documentation Fragmentation - Gerald Lasser - 2020-05-21

I think that is really the case.

Documentation is mainly split between the 'main site' and the 'parts tracker' and there are duplicates/references to each other. Like this example I just found where 'Unknown Parts Numbers' are once mentioned in the Official Standards and then again in the PT FAQ.

In the PT documentation there is also a lot of info good for parts design.


IMHO, some of the documents could have a bit more sturcture, i.e. paragraphs, bold stuff, etc.


RE: Documentation Fragmentation - N. W. Perry - 2020-05-21

As a relatively new learner of LDraw, I can definitely attest to this being the case. I often found I had to refer to multiple articles, even on the same general topic, such as the content of headers, meta commands, or how parts are numbered. There are two articles on colors, two on the OMR, etc. And information on official parts is largely documented at the Parts Tracker rather than the main documentation page at LDraw.org.

I think I understand why this is the case. Some of the articles establish and codify the LDraw standard itself, while others describe extensions to the spec. And different parts of the LDraw "universe" have different sets of rules: for example, the official parts library has formatting rules that aren't necessarily requirements of the LDraw format itself, so they're documented separately. (That does also lead to some discrepancies, however—for example, keywords are an official meta for parts only, yet there are standards for optionally using them in models. Do the same rules apply?—and so forth.)

For the end user coming in fresh, it can be a little daunting. I think having a single, unified LDraw "bible" would be a tremendous help for those who are new to this (and there are a lot of such folks out there), and would probably be mutually beneficial to the LDraw community by making it accessible to a wider user base. But I also know this would be a considerable undertaking, and I'd be willing to help with compiling, editing, proofreading, or whatever could be useful.

n.b.: There is the web page by J. C. Tchang, which compiles all LDraw standards and specs into one huge article in French. A single standalone document is pretty unwieldy, though; ideally I think you'd want something better organized and indexed.


RE: Documentation Fragmentation - Orion Pobursky - 2020-05-21

(2020-05-21, 16:25)N. W. Perry Wrote: There are two articles on colors, two on the OMR, etc.

Can you point me to these duplicates?

(2020-05-21, 16:25)N. W. Perry Wrote: And information on official parts is largely documented at the Parts Tracker rather than the main documentation page at LDraw.org.

This exactly what I want to get away from. I want everything in one place, clearly labelled as to purpose

(2020-05-21, 16:25)N. W. Perry Wrote: Different parts of the LDraw "universe" have different sets of rules: for example, the official parts library has formatting rules that aren't necessarily requirements of the LDraw format itself, so they're documented separately. (That does also lead to some discrepancies, however—for example, keywords are an official meta for parts only, yet there are standards for optionally using them in models. Do the same rules apply?—and so forth.)

This is why things are broken up in the menus between "File Format" and "Official Library". I think that maybe everything under the "Official Heading" can be combined into one standalone document. As far as "File Format", those documents need to be separate since they outline the core spec and the various extensions.

(2020-05-21, 16:25)N. W. Perry Wrote: I'd be willing to help with compiling, editing, proofreading, or whatever could be useful.

This what I want. Perspective from someone just starting out. Be bold with your suggestions. If you want, make a visual mock-up of how things should look. I suck at creating UI from whole cloth but if you give me a visual template, I can replicate.


RE: Documentation Fragmentation - Chris Dee - 2020-05-21

(2020-05-21, 9:37)Gerald Lasser Wrote: I think that is really the case.

Documentation is mainly split between the 'main site' and the 'parts tracker' and there are duplicates/references to each other. Like this example I just found where 'Unknown Parts Numbers' are once mentioned in the Official Standards and then again in the PT FAQ.

In the PT documentation there is also a lot of info good for parts design.


IMHO, some of the documents could have a bit more sturcture, i.e. paragraphs, bold stuff, etc.

In general, I am happy to see documentation move from the Parts Tracker to the 'main site', so long as information is not lost. Maintenance of (relatively) static content should be easier in the CMS.
Dynamic content could be moved but would require any existing (Perl) scripting to be re-worked as (PHP) extensions the CMS (typically CMSMS modules). This development effort would require re-work if we switch (again) to another CMS.


RE: Documentation Fragmentation - Orion Pobursky - 2020-05-21

(2020-05-21, 20:40)Chris Dee Wrote: In general, I am happy to see documentation move from the Parts Tracker to the 'main site', so long as information is not lost. Maintenance of (relatively) static content should be easier in the CMS.
Dynamic content could be moved but would require any existing (Perl) scripting to be re-worked as (PHP) extensions the CMS (typically CMSMS modules). This development effort would require re-work if we switch (again) to another CMS.

Correct me if I'm wrong but I think the only dynamic content is the primitive reference. When/if I move anything, I'll definitely discuss it with you first.


RE: Documentation Fragmentation - N. W. Perry - 2020-05-22

(2020-05-21, 16:55)Orion Pobursky Wrote: Can you point me to these duplicates?

For colors you have:
https://www.ldraw.org/article/299.html (describing the language extension including color parameters)
https://www.ldraw.org/article/547.html (defining the colors themselves)

For the OMR:
https://www.ldraw.org/article/593.html (the guidelines for OMR-compliant models)
https://www.ldraw.org/documentation/ldraw-org-official-library-standards/rules-and-procedures-for-the-official-model-repository.html (rules for the repository itself)

Quote:This is why things are broken up in the menus between "File Format" and "Official Library". I think that maybe everything under the "Official Heading" can be combined into one standalone document. As far as "File Format", those documents need to be separate since they outline the core spec and the various extensions.

Sure, and I recognize the reasoning for keeping the documents separate. That's what makes me think the ultimate solution isn't so much to move the existing documents (though some reorganization may be a good idea), but rather an additional resources that compiles all the different information into one place, organized by topic and in some kind of logical sequence. It could either contain the actual specs in-line, or hyperlink to the individual articles where they stand.

Quote:This what I want. Perspective from someone just starting out. Be bold with your suggestions. If you want, make a visual mock-up of how things should look. I suck at creating UI from whole cloth but if you give me a visual template, I can replicate.

I'll put some thought to it, as time permits. Best way to start might be just coming up with an outline form, whether it's for a centralized documentation web page, or something separate like a manual or "bible".