Documentation Fragmentation

[Orion Pobursky]

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?

[Travis Cobbs]

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.

[Gerald Lasser]

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.

[N. W. Perry]

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.

[Orion Pobursky]

There are two articles on colors, two on the OMR, etc.

Can you point me to these duplicates?

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

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.

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.

[Chris Dee]

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.

[Orion Pobursky]

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.

[N. W. Perry]

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/ldra...itory.html (rules for the repository itself)

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.

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".

[Leonardo Gonzalez]

...
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.

Lately I've found myself trying to learn about how the part format works, and I've been reading through some of the documentation. I propose that the problem may be not just fragmentation, but in the navigation of the site. Allow me to give an example...

Within the Parts Tracker Reference: https://ldraw.org/library/tracker/ref/ lies this section (which I will refer to as the "FAQ page"):

!CATEGORY and !KEYWORDS FAQ
Information about using these meta-commands in part files.

All the information on this section is basically word by word inside the Documentation (which I will refer to as the "Documentation page"): https://ldraw.org/article/292

1.2.4.!CATEGORY and !KEYWORDS Language Extension

Perhaps given the fact that the Documentation page has been revised, it is better explained, better formatted than the FAQ page, and it even includes a table of contents that makes it easy to navigate (unlike the wall of text on the FAQ page). I would advice to just point the link straight to the Documentation page. Now this suggestion creates inconsistent menu navigation, which is quiet inconvenient, and confusing for the average visitor. Taking the visitor away from the Parts Tracker section menu and over to what seems to be the Main menu.

Here is a quick visual comparison between the main page menu and the Parts Tracker menu on desktop and mobile:

   
   

The Parts Tracker section appears to use a sub-menu of its own and doesn't even give the visitor the ability to navigate the regular "Main menu" unless they click on the top banner. It appears that the original design of using a red brick logo for the Main pages, green brick for the Parts Tracker, and blue for the forums needs a moment of consideration.

Note that the main page designates the menu item as Documentation with a drop-down list, making it easy to find the section you need within the documentation. In the Parts Tracker menu, the item LDraw Specifications is not a drop-down list. Instead this menu item takes you away from the Parts Tracker section (green) and into the Documentation in the Main pages section (red).

There are many approaches to explore here:

• Add a drop-down list on the LDraw Specifications menu item on the Parts Tracker, perhaps even duplicating the Documentation page.
  
• Add the Main menu (red section) on top of the Parts Tracker (green section) making navigation more accessible, even for mobile. This would require an evaluation of the menu tree to remove redundancies. (mock-up below)
     
  
• Move the Documentation section to a yellow brick section (called reference or something similar) that can be accessed by both, the main page (red section) and the Parts Tracker (green section). This would require further evaluation of the navigation tree and the creation of a single consistent menu item for this section on all menus. (logo below)
  
    reference_and_documentation_logo.jpg (Size: 10 KB / Downloads: 24)
  
• Merge the Parts Tracker menu into the drop-down list "Parts" from the main menu (red section). Eliminating the need for a sub-menu in the Parts Tracker (green section) This would require that the "Lookup" search box be added to the main menu (red section).
  

I'm sure there are more solutions to explore, comments, thoughts, feedback?

Sorry for the long post.


-Leo-

[Orion Pobursky]

Thank you for well though out and detailed suggestions.

As chance may have it, the reference duplication problem you detail in the first part of your post was fixed today when the LSB ratified the new library spec revision. A bunch of links and pages in the PT Reference section have been removed, retired, or redirected.

As for the second part of your post, the menu bar "problem". I'd love to fix this problem but here's the deal: the main site and the Parts Tracker run on very different software. In fact, the Parts Tracker is approaching 20 years old and is largely running on the same software (perl scripts) that it was when it was first started. The main site, on the other hand, has going through 3 major design and software revisions since. The 2 systems really can't talk to each other very well (really more of a PT problem that the other way) so they are kept separate. The day will come when "Parts Tracker 2.0" is made as we can more closely integrate things but that day is quite a ways off.

The above was a long winded way of explaining why the menus are different. The main site they are generate programmatically from templates and article listings. The PT they are hard coded. I also haven't put a huge amount of effort into making the PT "mobile friendly" like I attempted to do with the main site since the PT is really primarily only used while on the desktop. We will, however, probably eventually move the entire PT Reference section to the main site navigation tree, leaving only PT functions on the PT menu. I've also been exploring how to more closely tie the design of these 2 areas together (without breaking things) so I can make changes and have it appear in both areas.

I do, however, like your documentation banner suggestion and will look to incorporated it into the main site scheme.

Please keep the suggestions coming.