Some observations about our Contributor documentation

I think we got a little bent out of shape with the structuring of the texts.

  1. The article " How to edit files on the Pagure Web UI" is on the same level with “Contribution tools”, but it is a subcategory, in fact.

  2. We should name the tools less technically but more task orientated. Maybe something like (but somehow I miss our “7-steps…” title here)

    • Contribution Tools
      • Edit a single page in GitLab based repos
      • Edit a single page in Pagure based repos
      • Maintain documentation with online authoring environment
      • Maintain documentation with local authoring environment
  3. Instead of “How to tun a local preview” it might be more precise “Setting up a local preview” and link to it from the main text (How to …a local authoring environment), because running he local preview is already part of the latter text.

  4. Probably it would be good to get an additional text “Working with git for authors” which elaborates about working with a handling of branches.

  5. On the first level, I would like to replace “Write contribution to docs” with something like “Contribute to improve and expand docs articles” to make the wording similar to the other contribution type (“Contribute to keep … up and running”)

If we basically agree about the changes, I would start to implement it. Then we can discuss the details and further improve the text.

I missed finishing touches. Thanks for your feedback.

  1. When the article was brought back, the navigation file was amended by you. +1

  2. I oppose to additional categories like a single page versus maintenance. If you don’t intend to drop the definition ‘casual contributions’, your suggestion creates too many categories. Truly easy onboarding is when new comers don’t need to consult with four or five different pages to start their first edits.

  3. I’m not sure I agree with this. After I opened a MR on this, I shared my view on whether to combine two articles or not during Docs meeting. Two guides have different depths and purpose. My MR was accepted and approved by one of Docs members.

About renaming or redefining process, I think we could think of rules of thumb.

  • What isn’t working?
  • Who is affected?
  • Did we give users time to try out?
  • Are you making changes before users are comfortable with the new guide?

If it ain’t broke, don’t fix it.

  1. Which page do you suggest adding it? Local authoring guides have relevant paragraphs already.

  2. +1
    Levelling navigation file needs local preview before anyone merges PR.

I implemented No. 1. & No. 5. as we obviously agree about it.

regarding to No. 2. (naming of the tools)

I don’t intend to add more categories, but to allow a better and quicker orientation along the decision tree. The first level is WebUI vs. local environment. WebUI has a second level: pagure or GitLab. And GitLab has a third level. Profoundly or casual. The current naming does not make this decision tree clear.

So probably something like:

  • Use the Web UI for GitLab based documents making a casual contribution
  • Use the Web UI for GitLab based documents making a profoundly contribution
  • Use the Web UI for Pagure based documents (making a casual or any kind of contribution?)
  • Use the Local Authoring Environment for any documents and any kind of contribution

Regarding to No. 3. (Local Authoring Environment)

Yeah, nevertheless we should consider optimizing it. I would propose to restructure it as a kind of “Cheat Sheet” while editing an article. So the focus is the Workflow. And when you open the guide, the workflow should show up at the top of the article. The setup / installation part is only important once, at your first view. Later it is just annoying because you have to look and skip again and again.

Instead, the setup / installation should be at the end or - better - on an extra (sub-)page. And the local preview page is contentwise not a “how to run” but a “why you need, how to setup, and available alternatives” page. And it requires or is part of a local authoring environment. Therefore, it is structurally a subpage and not on the same level as the “main” page (Using Local Auth…).

As I said above, it is mostly just a restructuring and a UX optimization, not a rewording.

There is just another issue we should fix.

We have 2 guides about Quick Docs:

The latter is under “Contribution Tools” which is not correct because it is not a tool.

The two articles overlap to some extent. I would merge the two into one article if no one raises concerns.

On point 2, I understand the context, but names on menu bar could be concise.

Put the task in front not the order of classification. I haven’t touched semantics in the original title, but ‘profoundly’ sounds so unnatural. Could a native speaker offer a better suggestion, maybe?

On point 3, there may be countless users of local authoring environment, who don’t even have to look at the guide at all. Could you ask round a wider audience in Server group or other authors who are heavy users of local authoring/preview for sense check?

I’m not really convinced with merging or splitting existing articles. What’s the rush?

100% agreed. Do you think this applies to the current phrasing? To me, the items in the overall view make a confused impression. Each individual item is OK on its own. But I’m not a native speaker.

Yes, and for those we don’t need a guide at all, I suppose. We need it for those who are not familiar with git and the merge workflow and like to have a cheat sheet next to them when editing to look up the next step. And a good cheat sheet is as short and as clear as possible.

But there is no hurry. Let’s discuss this when you have finished with your current challenges.

Conciseness in wording on menu bar listing is lacking for both current and revised phrasing suggested by you, unfortunately. I can’t make suggestions on wording right now due to summer holiday.

What I mean is who we need to get a second opinion from, not target audience of contributor guides. I think we need to seek a second opinion from both those who don’t need the guide, but could give us down-to-earth and pragmatic advice, and those who need it next to them.

I argue you and I are the most biased individual in writing the contributor guides because we spent much time on it and form a judgment on what is convenient and annoying. I think we need to keep some distance to an urge to sub-optimize the guides from our judgment call.

From a recent weekly meeting on 21 June, we have potential source of feedback from a new contributor @riddled . We need fresh insights and ideas.

Furthermore, we need a quick sense check by native English speakers to ensure clarify and brevity of classification because a choice of wording sometimes comes off odd.

Yeah, it’s probably a good idea to gather some feedback from people not so closely engaged in creating ad maintaining the articles. Maybe, there are some opportunities during FLOCK.

I think I would use major or minor change. Or if you wanted to continue using casual, you could use casual change or involved change. Instead of saying “How to profoundly use GitLab UI for document maintenance”, I would say “How to use GitLab UI for more involved document maintenance”

I would be glad to help. I haven’t had a chance to look at the Contributors Docs yet. I had some stuff come up. But I am planning to sit down and deep dive starting tomorrow morning.