Initial User Guide Reorg and Introduction of Customer Life Cycles

[vanmaegima]

PR Template and Checklist

Please complete as much as possible to speed up the reviewing process.

Readiness and adding reviewers as appropriate is required.

All PRs should be reviewed by a technical writer/documentation team and a peer.
If effecting customers—which is a majority of content changes—a member of Customer Success must also review.

Readiness

• Merge (pending reviews)
• Merge after date or event
• Draft

Overview

This brings a User Guide reorganization based on the customer journey so steps can be approached in a understandable way.

This also brings the Customer Life Cycle view of the docs, which covers a doc view based on journey/personas.

Checklist

• Run spelling and grammar check, preferably with linter.
• Avoid changing any header associated with a link/reference.
• Step through instructions (or ask someone to do so).
• Review for wordiness
• Match tone and style of page/section.
• Run make linkcheck.
• View HTML in a browser to check rendering.
• Use semantic newlines.
• follow best practices for commits.
  • Descriptive title written in the imperative.
  • Include brief overview of QA steps taken.
  • Mention any related issues numbers.
  • End message with sign off/DCO line (-s, --signoff).
  • Sign commit with your gpg key (-S, --gpg-sign).
  • Squash commits if needed.
• Request PR review by a technical writer and at least one peer.

Comments

Any thing else that a maintainer/reviewer should know.
This could include potential issues, rational for approach, etc.

[doanac]

Docs for 58b547e are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2595/docs/artifacts/html/index.html

[vanmaegima]

@mike-scott @kprosise @angolini @caiotpereira Draft view so you can check the compiled page.
I didn't like the initial propose, which made the User Guide view huge:

So I'm proposing this new LifeCycle view which will also include personas. I'm still not very happy about it so please provide your feedback.
This is draft only as we are missing several pages (explaining the life cycle, personas, production, etc). If the team agrees this is the best path to go, then I can work on those pages.

[angolini]

From the previous discussion, I understood we would replace the part "User Guide" with another part; from the PR, it would be the "Life Cycle / Customer Journey / Good Name Here".

@kprosise, do you know if there is a way we can display levels 1 and 2 on the sidebar?

[angolini]

Overall, I like the change in the order. But I still don't like the sidebar

[vanmaegima]

@angolini I agree with displaying multiple levels on the side bar, I played with it for a bit but couldn't achieve anything.

[angolini]

@angolini I agree with displaying multiple levels on the side bar, I played with it for a bit but couldn't achieve anything.

In the past, I have also tried and could not find a way.

[vanmaegima]

I did a sync with Mike on this and from this I will propose a few more changes to this, the biggest one being dropping the new life cycle section. We will cover personas at the top of each section.
I will rework this tomorrow and propose the changes in a few pages so we can check.

[kprosise]

@angolini @vanmaegima let me look into the side bar levels thing. It should be possible, will likely just require modding the theme a bit. Let me spend a little time today to see what I can come up with.

[vanmaegima]

Updated docs with suggestions from @mike-scott , PTAL.
See pages Factory & Account Management and Custom CI for an example on the suggestion to handle Personas.

[kprosise]

Re: side bar levels, it will unsurprisingly require a deeper dive into what is going on. All my attempts today at changing anything related to the theme produce nothing. I will spend a bit more time looking into it out of curiosity before moving on for the time being.

[doanac]

Docs for b6f3e22 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2598/docs/artifacts/html/index.html

[kprosise]

I am liking this reorganization so far!

[kprosise]

This can be done after the merge, but for all pages moved to a different section, we should likely add a redirect in source/conf.py

[vanmaegima]

@kprosise I'm reworking this PR, can I get an example on what do you mean with this comment? I see the redirects in conf.py but it's not clear for me what it means.

[kprosise]

Just so that anyone going to latest/reference-manual/qemu/qemu.html and the other pages don't receive a no-such-page error, as the pages will  now be under latest/user-guide/qemu/* , but it's not too important at the moment.

[vanmaegima]

@kprosise I reduced the scope on this PR (removed personas and new pages that I'll cover on the next PR per discussion with Mike). Now it only covers:

• reorganization of UG
• QEMU section change to UG (with redirect - can you please check if I did it right?)
• duplication of RM pages in UG for better user experience (need UG specific pages in the future)
  Let me know what you think and what it needs to get it merged.

[doanac]

Docs for 171b6e9 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2622/docs/artifacts/html/index.html

[kprosise]

Looks good to me! We can do future tweaks if need be, but I think this is a good step towards the reorganization goal! The redirect works as intended. :)

[vanmaegima]

@kprosise We can merge this whenever you're ready then! I'll send another one after this is merged.