Preparing the Docs meeting: Discussing how to integrate the HowTo

Project Discussion
1

I think we are on a good way to a well HowTo that is developed in conjunction with those who are supposed to use it. See the development of the discussion.

Some questions I would like to put forward to talk about in order to make a decision somewhen in the next meetings:
→ does it make sense to add the 7-click HowTo (or another one?) to the Fedora Docs page next to the existing buttons to have it at first glance? (current buttons are “history”, “edit the page”, “create ticket”)
→ how to passively forward the information “it is easy, it is quick, it does not need preceding knowledge” to potential contributors? Does it make sense to make this a text button with a corresponding message? E.g., a “HowTo: 7-clicks to an edit” button?
→ does it make sense to remove the “history” button there?
→ what format should the HowTo have? Shall we link to a PDF, which is something everyone is used to, or shall it be itself a Docs page formatted in AsciiDoc?

The questions are already elaborated in the discussion mentioned above.

Most related posts for these questions:
1 2 3 4

1 Like
2

I think it would for sure be useful and helpful. And I see no impediment to adding a link, either a 4th button or changing the current edit link to a dropdown item with “Edit” and “How To Edit” (or something similar). We need a stable link though, so need to update our team page as soon as possible.

→ how to passively forward the information “it is easy, it is quick, it does not need preceding knowledge” to potential contributors? Does it make sense to make this a text button with a corresponding message? E.g., a “HowTo: 7-clicks to an edit” button?

That’s a good idea. I think we should develop a “campaign flag” which we add beyond the Contents list, at least temporarily.

1 Like
3

If we can figure out a way to easily represent that across languages/cultures, absolutely.

Putting it in the footer is probably the easiest/best approach.

I don’t see why. The history of that page is no less relevant than the history of any other page.

If we make it a PDF, it still has to come from somewhere. Doing it as an AsciiDoc page within the same repo makes the most sense to me.

4

Well, I tend to look to the footer if I explicitly look for something like a contact form, or website-related help pages. But for making people aware who are not explicitly searching for contribution possibilities, who have maybe some “it’s git and too complicated anyway” prejudices in mind, I would suggest to put it simply next to the existing buttons? The top is where people generally look at first. And I think the buttons we already have are placed well.

Well, my thought was not that it is not important (I absolutely agree on your argument!), but that people who work with the history tend to work from within GitLab. But this is not an important point, and there is no issue with keeping the button.

For this point, I have no preference tbh. If there is a consensus towards one possibility, I will prepare a draft for that. If all agree, I will prepare a AsciiDoc draft in the coming days.

5

Sure, but how do you represent it in a button? That’s my concern trying to put it on the top. Footer text, while less visible, is much easier to explain in a way that conveys what’s going on.

6

Just a “quick and dirty” example of what I originally meant:
7clickButton

I admit that the downside is that it is perhaps a bit too much of a focus.

7

Following Docs meeting today, I would think of more Call to Action “verb,” for example;
Edit page in 7 steps
Edit the docs in 7 steps
Fix me in 7 steps
Improve the docs in 7 steps

Call to action words without adjectives or adverbs should work fine. All arguments come from subjectivity, which dilutes our effort and intention.

1 Like
8

That approach makes absolutely sense to me! Although I would use “page” instead of “docs” (so that it is clear this is explicitly about the opened page(s) and not something general). So my favorites would be

  • Edit this page in 7 steps
  • Improve this page in 7 steps
  • Edit me in 7 steps

I like the simple “fix me in 7 steps”, but it indicates that this is only about correcting errors.

1 Like
9

I created an asciiDoc draft:

Unfortunately, in asciiDoc, borders around images seem only possible with a table, and a table cannot be centralized. However, I think it fits the needs, and it will look better than now if it is opened within a Fedora Docs page.

1 Like
10

I would suggest alternative words to describe our dear contributors rather than sporadic.
“Long tail” contributors

Taken from ideas of Anne Gentle, who is ‘Docs-like-code’ author and practitioner; quoting her words “Split deliverables into parts that encourage small but mighty contributions.”

Sorry to be picky, but the title is more than semantics.

11

You are right! That is still the initial working title, at some point I did no longer think about it. Indeed, that should be changed. “Long tail contributors” sounds good, but I never heard that. What does it imply? Will people understand what we mean with that? Maybe we could use something that is more obvious and clear also to non-native speakers. “External” is clearer, but it does not sound nice either. Is “casual” an alternative?

12

I agree with @hankuoffroad’s concern, but I don’t think “long tail” has a clear meaning. I’d lean toward “casual” or “infrequent”. “External” is confusing: external to what?

1 Like
13

I changed it to “casual” for now. I can change it again if a consensus develops towards something else :+1:

1 Like