Improving Docs team page (step 2 of n)

Project Discussion
1

I would like to share some ideas that we might discuss here and/or on our next meeting.

  • Currently not the moist urgent activity
  • But as soon as we start to campaign docs, e.g. publishing to comm blogs and try to attract the community, we’ll get subject to the wide-spread procedure today: search & check them.
    • Someone who gets curious about us will “search the internet”, looking for primary information, i.e. a project’s or person’s homepage, and secondary information, e.g. test reports, field reports, and information of what the project or item successfully did recently.
    • We have to avoid that someone reads through all the pages and afterwards still doesn’t really know what we do, how we do it and what we have achieved so far (and what a nice and friendly community we are).
    • In a time frame of about 8-10 weeks we should have a team page which does not give the impression of being a barely acceptable, unloved stopgap solution.
  • We should document our current work structure, as far as it is not too cumbersome
  • Create an archive of previous results and activities. Probably start with information where to find the outdated pre Antora docs (the repositories)
    • goal here: we are not newbies, but a long term effort with remarkable results so far.
  • We should update the contributors section

Potential extended structure of the Contributor pages

  • How to contribute (page)

    • content contributions

      • Many ways for various type of contributions, e.g. typo fixes, adding short information, e.g. a link, update an article, contribute a new article.

    • General procedure:

      • A author contributes a git “pull request”, i.e. a modified version of a documentation item, mostly a page.
      • A member of editorial boards checks and publishes or asks questions. Allow 2-3 days for a answer to an request.

    • Ways to contribute

      • Editing the file
      • Using the Web authoring interface
      • Creating a local writing environment

    • Design contribution

      • TBD

    • Technical contribution

      • TBD

  • Content contributions (page)

    • Ascii Doc (subpage)
    • Style Guide (subpage)
    • Using file edit interface (subpage)
    • Using web interface (subpage)
    • Using local writing environment (subpage)

We would get a new main navigation:

  • Fedora Docs Team
    • Fedora Docs team members
    • Fedora Docs infrastructure
    • Communication and meetings
    • How to contribute
    • Archive
4 Likes
2

This all looks good to me. I think the layout makes sense and it will definitely help us onboard new contributors.

1 Like
3

As discussed at our meeting, I created a branch stg in our repo and created a new structure of our team pages in it. Unfortunately, I can’t find a link to the local preview but probably some of you are smarter and more familiar with GitLab and can find out. I’m fine with my local preview.

From my POV we should discuss

  1. The section “Contributing” is a separate Module with its own navigation. Therefore, it is not possible to integrate it in the team page navigation, as I would like it, but just append it to its navigation.
    I don’t know why it is separate. If we want to publish it elsewhere apart from our team pages, it is easier to do so. If not, isn’t it easier and more flexible to integrate it into the ROOT module (our team page).

  2. The same is true for the “AsciiDoc for Fedora” part.

@hankuoffroad Look at the stub page use-web-ide-ui.adoc, that for you. :slight_smile:

1 Like
4

I don’t know why it was originally created as a separate module, but I don’t see any reason why we shouldn’t collapse all three of them into a single ROOT module.

5

You’ll need to create a Merge Request to trigger the build (I’ve made one for you). Don’t need to merge it or anything yet and it’ll get automatically updated as you push more commit to your branch.

You’ll get to the preview by clicking the [View app] button:
image
(note that the link provided here is temporary, and will get regenerated when you update your branch)

6

Thank you for that. Will work on the content.

7

OK, if nobody else objects today or tomorrow I’ll move everything into a single ROOT module with the next optimization cycle 2nd half of this week

Thanks. I didn’t dare to generate a merge request, not that a “helping hand” would take care of the pending request.

1 Like
8

I’ve just updated the stg branch to the new structure, as discussed.
We should consider whether we do not flatten the menu hierarchy somewhat. E.G. we could split the contribution menu item in “Contribution to doc content” and “Contribution to Design and Web Interface” (or a better wording). The hierarchy is currently somewhat unbalanced.

And we should discuss how to proceed now. E.G. we could feed the current content into the new structure and then change the current pages to the new structure. This makes it easier to gradually add more content, e.g. using the file edit option.

1 Like
9

I don’t have a strong opinion either way. I don’t think the unbalanced heirarchy is per se a problem. On the other hand, “Building a local preview” could probably move out a level as it’s relevant to both wording and design changes.

10

I’ve finished a version of the team page today, which is complete enough to get published (each page is fully formulated and self-contained), but still lacks several parts, especially the part about git workflow.

So we should decide whether to publish now or to wait until the next step is completed.

For that completion, I would need about half a day or so, but I can’t foresee if I can fit it into my to-do list this week.

11

I say we publish what we have and add to it as we go.