Question on Quick Docs and include directives

Project Discussion
1

I have a question on using the AsciiDoc include directives in Quick Docs.

I’m working on Quick Docs issue #189, Setting a key shortcut to run an application in Gnome.

Looking at the issue, I agree with the comment from grumpey that the Quick Doc in question should be merged with Managing keyboard shortcuts for running an application in GNOME. This document is a little out of date and needs new screenshots, but is otherwise OK.

As I’m looking at the relevant .adoc file, I notice that it uses a number of include:: lines:

include::{partialsdir}/proc_adding-shortcut-custom-app-gnome.adoc[]
include::{partialsdir}/proc_disabling-shortcut-custom-app-gnome.adoc[]

Looking through a number of other .adoc files in that directory, I see that about half of them use include directives while the rest just have the content in the topic.

Question: is using theinclude directive recommended, or was that just a choice made by the original authors? Can I pull the content referenced in the include directives into the main .adoc file?

Further context, since there is a higher-level discussion going on about onboarding new contributors: if I were someone trying to contribute to a topic in Quick Docs and came across a file full of include::{partialsdir} lines I wouldn’t really know how to proceed. I think using include directives for general body content in a topic makes it difficult for people to contribute.

Speaking as a professional technical writer, I would also say that using an include for body content isn’t what they’re for. Something like an include directive is designed for something like an admonition that has to be included on multiple pages or a short snippet of code, not for paragraphs of content in a topic.

Let me know what everyone thinks. I like the idea of includes (I use them quite often in my day job, where they’re called snippets), but I don’t think they’re being used correctly here, at least not in a lot of cases.

1 Like
2

Your points make sense to me. Using those includes like that was likely just a choice someone made at the time. It is difficult to speculate what they were thinking. The docs are in such poor shape that having people step forward to maintain them is more important than striving for consistency at this point (especially for something “behind the scenes” like the use of those includes).

So you have my full +1 to do it your way. :slightly_smiling_face:

3

I do not see that includes are useful at this point. The includes are so special that they are hardly reused in other articles.

Therefore, I suggest moving the includes into the text body.

We had briefly discussed this in one of the IRC meetings some time ago. If I remember correctly, we had not made a decision, but no one spoke out in favor of keeping the includes.

I would appreciate it very much if you immediately start to remove the includes.

Fully agreed. Includes should be an exception for cases, where reusability is a real need and proven benefit.

We should therefore proceed in such a way that we basically resolve all includes, unless we actually find multiple uses.

Practically, it would be important that you rename the integrated partials afterward, e.g. to *.adoc-2delete. We can then quickly find cases where they are used again and take action.

I think, there are other cases, too. An example are our prerequisites for contributing. An include instead of a link can improve the reading flow. But some QD items are a collection of includes. I can’t see any sense in that.

4

When we built this, originally, there was a whole theory about building reusable content snippets from the Red Hat docs team — instead of linking to how to install a package everywhere instructions for that might be needed, or repeating, there would be lots of little Lego blocks of content that could be snapped into place.

I see the appeal — write once, use lots of places, and if there is a change, everywhere benefits. But I also agree with you that it increases complexity.

The people promoting this approach never actually showed up to help. So… eh?

5

However, I still think there should be some ‘common’ text(s)/content/snipets used for Fedora docs. I liked the concept of ‘common content’, for example, used in the time of publican. An example could be something like feedback.adoc?

It might perhaps facilitate translation, too. It’s really time consuming if you translate the same content several times as it is (re)used in differerent documents or websites. Though, there are tools like translation memories. But imagine if, then, the same content is updated in each place in different time…

But overuse of includes is definitively not right.

6

Thanks for the feedback everyone. I’ll unwind the includes in the Quick Doc I’m working on now, and will do the same for any others I touch.

And to be clear, I’m very familiar with the use case around includes for reusable content and for content that needs to be written once but displayed in multiple topics or in multiple outputs. This is something I use in my day job on a frequent basis for the documentation I maintain.

But the way I’m seeing them used 99% of the time in the Quick Docs I’ve checked doesn’t match that use case. It seems like they’ve being used for unique body content that isn’t being reused anywhere else.

To @mattdm’s point about this coming from the Red Hat docs team - I can see why they’d make heavy use of includes for a lot of their documentation, since they deal with versioned enterprise products that probably contain a lot of the same base content. That just doesn’t seem to be the case with the docs I’ve seen here, though. So the intention was good, but the suggestion wasn’t really applicable for this project.