solidus

solidus copied to clipboard

Navigating code is challenging for new adopters. Can we create some sort of technical reference? Perhaps with automatic generators from comments blocks, if we have any?

We have API documentation, but it's not complete. For example, if you wanted to see the document for the Spree::Payment class, you would look it up here: https://www.rubydoc.info/gems/solidus_core/3.2.3/Spree/Payment

Is that what you had in mind? The API documentation is admittedly incomplete, but it's definitely a start.

Yep, it is based on https://yardoc.org/ code comments.

A good idea could be copying a lot of the legacy guides as top-level class documentation for our primary models. This way, we won't lose that important information, and we will have more complete API documentation with a low effort.

I tend to think that making that in-code documentation (and thus the API docs) really good is a really high-leverage way to improve the Solidus documentation situation. The guides are great too, especially for lengthier and more high-level topics, but difficulty navigating the framework is something we see people complain about, so any effort to make the API docs more robust and complete (like you're suggesting with copying in the legacy guides) and in so doing add context for people reading the source would be a win in my book.

That sounds great. If the core team approves of @kennyadsl's idea I'm happy to contribute to transferring legacy guides into the source.

I also like @kennyadsl's suggestion. From the feedback we have gathered, and as @jarednorman is confirming, approaching the codebase appears to be difficult even for seasoned developers. Any effort to lower the adoption barrier would be greatly appreciated. Later today, we will discuss and plan about Alberto's plan and see if we can take an incremental approach there. Once we have agreed on doing this and established a process to include the legacy guides, some additional help would be highly welcome. We will keep you posted, guys.

When we did consider this topic in the past, we also did create a bunch of issues on the edgeguides repository, because this was part of the migration from the legacy to the new guides. These are probably the quick win tasks for a copy/paste action from the guides to code as YARD, but I expect there will be more work once we start. As you can see, those issues are closed now because for some reason we deprioritized that work, but we can reopen and move them to the right place.

@benjaminwil your help would be fantastic, and I would be glad to see you have other ideas on how to better accomplish this task. Let me know!

Copying the legacy guides over the corresponding classes will be an improvement of the current situation, but if we do that blindly, we face two problems:

• The legacy guides are sometimes inaccurate, as they haven't been consistently updated.
• They weren't written as reference documentation, so they are wordy and add noise to navigate the code.

To be clear, I'm not against the move, but we should make sure we don't stop there, as it'll be derailing us from our purpose to have well-structured documentation. The following is from the "Reference" section of Diátaxis, the documentation framework we agreed to follow:

Reference material should be austere and to the point. One hardly reads reference material; one consults it.

There should be no doubt or ambiguity in reference; it should be wholly authoritative.

Reference material is like a map. A map tells you what you need to know about the territory, without having to go out and check the territory for yourself; a reference guide serves the same purpose for the product and its internal machinery.

Although reference should not attempt to show how to perform tasks, it can and often needs to include a description of how something works or the correct way to use it.

Some reference material (such as API documentation) can be generated automatically by the software it describes, which is a powerful way of ensuring that it remains faithfully accurate to the code.

@waiting-for-dev fully agree. That's not something that can be copied/pasted blindly as they are, for the reasons you mentioned. Also, this has nothing to do with the work we have to do on the guides. It's more to have better API documentation that will support the official guides, similarly to what Rails does:

• https://api.rubyonrails.org/
• https://guides.rubyonrails.org/index.html

@kennyadsl, thanks for getting back. Ideally, I'd like to see the yard docs as the "Reference" part in our documentation ecosystem, while the guides would cover "Tutorial", "How-to," & "Explanation". Although I understand we're far from there and any step to improve what we have is something good 🙂

We will take an incremental approach but must agree on a plan and document the process.