Regarding out teampage local authoring environment

Project Discussion
1

For some reason I couldn’t reply to a gitlab message from @hankuofroad .

As a result, the old page https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/tools-localenv-an-introduction/ and sub pages still remain.
The new page does not appear on navigation tree on the left. https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/local%20documentation%20workflow/
I managed to edit nav.adoc file thanks to local preview (trial and error).
The file is here. How can I make a change?

I’ve fixed that

  • copied the nav.adoc over
  • removed spaces from the file name
  • rename file according to naming convention

After being able to read the text in the full context, i would suggest some modifications:

title: Keeping the author-oriented terminology, local authoring environment

Structure: improving UX, Reading flow, readability: Increased hierarchical structuring of the headings including including typographic assistance. It’s non content related, just formatting.

How can we discuss that?

2

Thanks for suggesting that and updating navigation tree. I deleted the comment as soon as I saw your update. That’s why you weren’t able to comment.

I figured out how to update nav.adoc, but maybe next time.

title: Keeping the author-oriented terminology, local authoring environment

I’m with you in principle. But on the word choice, I suggested writing instead of authoring. It is purely semantic and my preference to call something in a simpler term. It is something like eating or dining.

Structure: improving UX, Reading flow, readability: Increased hierarchical structuring of the headings including including typographic assistance. It’s non content related, just formatting.

Edited: in retrospect, do you think section == is too large for each process step?
Maybe we could reach a happy medium to restructure that to look more natural.

About typography, minimalism is generally acceptable for readability. If we consider text-to-speech scenario and accessibility, flat structure and no hierarchy are better than multiple section levels.

Well, that’s my opinion. Docs are living documents, and workflow can diverge, so let’s discuss and wait for comments for improvement. Thanks.

4

I largely agree with you and do not think that we have very different conceptions. According to my impression, the page becomes somewhat unstructured and not so easy and quick to grasp because of the many, quite “strong” headings.
I am thinking more of something like
https://fedoraproject.org/wiki/Server/Documentation/How_To_Contribute#Setting_up_an_authoring_environment

2 Likes
5

I updated my local authoring environment with the updated content, fixed the issues und pushed everything back.

As fas as I see the site works well.

6

I reflected on your point and I agree the strong headings (although I was so used to other pages overall with the style) can be seen like shouting in block capitals in writing,

I actually read the Server Wiki pages several times and I got carried away for testing git workflow.

Please let me restructure headings and steps for better flow. Thanks.

7

New MR submitted for your review. Managed to resolve merge conflicts. Mea culpa.

Edited: I used bold text only to highlight actions in GitLab UI (like press blue button). I didn’t use numbered list throughout or bullet points/indentation. I kept simplicity of flow. The article does not show complex routines, so I suggest flat structure.