search

oqtane / oqtane.docs

Oqtane documentation auto-generated with Docfx
MIT License
17 stars 18 forks source link

Enhance Documentation Layout #16

Closed thabaum closed 7 months ago

thabaum commented 10 months ago

Proposal

To better server Oqtane community utilizing the Oqtane Documentation I would like to propose updating the main home index page to better reflect all the features and areas needed to help support the framework. I am currently looking for any feedback in the event I attempt providing a pull request for this down the road.

Current Outline For Reference: image

Issue

There are a lot of features in Oqtane that currently have little or no documentation for users and developers. Some because they never existed before. We need a way to highlight most common uses and branch out topics from there. So a near full rehabilitation here I believe is needed to provide the best documentation for Oqtane 5.x and higher.

I understand the current outline and layout works in many cases. The below topic structure is going to change according to what is already here and I will adjust it further once I review how it can merge more with what currently exists.

Solution

Enhance the homepage by turning it more into a table of contents with links to each section described letting everyone know what is expected to be in these main sections which can be modified as needed. We can get these pages decided on as some maybe missing like DB-Schema page, how they should be organized and then initially setup we can begin to improve documentation. This should help users find information on the different main features Oqtane Framework has to offer to both developers and administrators in a clear way with easy to understand workflow.

Community members working on documentation can more easily understand what topics need to be generally covered. A lot of content to document for things like troubleshooting and tips can be found in posts on GitHub, Oqtane Blogs and other sources into these document files to help support this level and type of organized content.

General outline proposed for our documents homepage

Note this would be with links going to the anchored information on the page and the description will include the link(s) to the pages related to each topic with it's dedicated information but these are not currently included in the example below as this is current a rough draft and a work in progress:

Oqtane Framework Documentation 5.0

Welcome to the documentation for the Oqtane Framework version 5.0. This guide provides comprehensive information on the various features and capabilities of the framework.

Table of Contents

Introduction

Oqtane is an open-source CMS and Application Framework designed for developing web, mobile, and desktop applications on the .NET platform. It utilizes Blazor to create dynamic digital experiences and can be hosted on various platforms, including Blazor Server, Blazor WebAssembly, or Blazor Hybrid (via .NET MAUI).

Getting Started

User guides on how to get started with Oqtane, requirements, installation instructions, and basic setup.

Features

Themes

Explore the theming capabilities of Oqtane to customize the look and feel of your applications.

Theme Development

Learn about developing themes using the Oqtane Framework, enabling customization's to the visual aspects of your applications.

Modules

Discover and utilize various modules and plugins to extend the functionality of your Oqtane applications.

Module Development

Learn about developing modules using the Oqtane Framework, including creating custom features and functionality.

Marketplace

A new addition to Oqtane, the Marketplace feature facilitates the discovery and installation of third-party modules, themes, and extensions directly from within the Oqtane platform.

Administration

Explore the administrative features of Oqtane for configuring and managing the framework.

User Management

Understand the user management features provided by Oqtane for authentication and authorization.

Security

Explore the security features of Oqtane to ensure a robust and secure application.

Multi-Tenancy

Learn about the multi-tenancy support in Oqtane for managing multiple sites within a single installation.

Advanced Topics

Internal Architecture

Tutorials

Step-by-step tutorials for common tasks and scenarios in Oqtane development.

Troubleshooting

Troubleshooting guides and common issues encountered by users, with solutions and workarounds.

Community and Support

Connect with the Oqtane community, find support channels, and get involved in discussions.

Contributing

Oqtane documentation is a collaborative effort. We encourage community members to contribute and improve the documentation.

How to Contribute

  1. Fork the repository.
  2. Make your changes.
  3. Submit a pull request.

Contribution Guidelines

Release Notes

View the release notes for each version of the Oqtane Framework.

Version 2 Merged Attempt 1.

Oqtane Framework Documentation 5.0

Introduction

Getting Started

Features

Development

Theme Development

Module Development

Framework Development

.NET MAUI App Development

Resources

Tutorials

Troubleshooting

Community and Support

Contributing

Release Notes

PROPOSAL SPECIAL NOTES:

Old Page Retention:

- Do not remove the old page when it gets moved.
- Ensure the old page remains accessible at its original URL.

Copy to New Location:

- Copy the content of the old page to its new location.

Update Menu:

- In the documentation menu or table of contents, update the link to the moved page to reflect its new location.

Update Message:

Include a prominent message at the top of the old page.
    - Clearly state that the page has been moved.
    - Provide a direct link to the new location.
    - Consider adding a redirection notice for a specific period.
    - Consider redirecting the page HTTP request when old page is visited.

Some links may go to single page documentation resources while others go to new manual sections such as API, Administration and Articles currently do.

Most of everything should stay right where it is, but a few pages I suggest moving. For example "Installation" can be moved to "Getting Started" out of "Administration" by removing its link out of the navigation tree menu and using a notification message at the top with a link to forward the existing users that find the page from links for example links posted in forums directing them to visit the new documentation page dedicated to Oqtane installation.

Articles is the only one I am questioning but I would like to break this down further moving concepts under introduction and Articles under Tutorials with Videos. Seems like they are mostly tutorials using blogs but I am sure videos will become generated down the road by the community. These relating videos and articles can be included and grouped by category after reviewing the content they contain.

It would be nice to investigate ways to simplify some things or unify them when needing updated. I am not 100% sure what can or can't be done in regards to this area as I am still feeling things out. For example things like the contribution link or a footer with version information that you edit one file and it updates all 40 files.

Last Note: This is a lot to do on it's own and it is great to see a lot done for API, Articles and Administration. It would definitely take some time laying down all the ground work and community members filing in the blanks here. DocFX is a p@!n in the you know what if you know what I mean. After finally providing some PR's for Oqtane Documentation I seen this is one heck of a task to build and maintain.

Flat out this is a job... but once it is set in motion and gets close to a safe destination of completion an incredible resource this will be if we adopt one of these proposals to build upon. I am laying into proposal 2 myself as I have that one most refined but can be adjusted as desired by the community to make the most logical sense.

The goal is to get people cruising around heading in the right direction by lifting up the fog a little making the experience more engaging to explore and discover things as soon as they make the choice to visit the Oqtane documentation. It would be encouraging to hear the community speak very highly of the documentation with it more considered the go-to resource to find a lot of information that would be nice to somehow present.

I would not mind linking the Oqtane Framework messaging for some areas to documentation such as installation as well with an on/off switch on if you want to enable or disable allowing the documentation links in the framework. If we can get certain places in documentation to be easier to convert to a company brand editing just a few files that would be pretty choice.

I look forward to any feedback, cheers!

thabaum commented 10 months ago

Supporting Oqtane.Docs with DocFX Enhancements 🚀

Hey Oqtane crew! 👋

Just wanted to give you a heads up that I've been eyeballing ways to jazz up our Oqtane.Docs using DocFX. But, here's the scoop:

Why the Spotlight on Oqtane Learn Proposal?

Hold on to your rocket boosters! 🚀 The Oqtane Learn Proposal is on the horizon. This bad boy aims to cook up an Learn.Oqtane.org website and Oqtane.Learn module project for turbocharged learning features. Imagine the possibilities!

What's the Play?

Let's pump the brakes a bit on DocFX glam until we get more buzz around the Oqtane Learn Proposal. This project is like the DJ at the Oqtane party, spinning tunes that get everyone on their feet.

But, DocFX Still Rocks!

Don't stash away your DocFX wizard hat just yet. If you're feeling the DocFX groove, dive in and sprinkle some enhancements for Docs 5.2 and beyond. Your moves will keep our documentation dance floor alive and kicking! It is currently owned by the .NET Foundation and community driven like Oqtane!

Oqtane Unity 🤝

Let's rally around discussions that ignite the Oqtane community. The goal is to craft a learning utopia for all Oqtane enthusiasts. Together, we'll make learning the Oqtane way a piece of cake. 🍰

Ideas from this documentation enhancement I am suggesting can still be useful for feedback and ideas.

Looking forward to your thoughts and sparks of genius!

iJungleboy commented 10 months ago

There's a lot to unravel here ;)

I have a lot of tricks up my sleeve based on the experience with 2sxc. Eg. how to restructure pages and still preserve old links, which are then in the "wrong" place but not have them in the navigation.

It would be hard to document them here, but I think we would discuss most of it at an upcoming meeting ;)

thabaum commented 10 months ago

I agree this is going to be a challenge after reviewing. A meeting at some point would be ideal for addressing these concerns the best.

thabaum commented 10 months ago

@iJungleboy I like the direction you are going with Oqtane Documentation layout. I put down pretty much the areas I felt should be in the outline that we can discuss further at a meeting to build on these synergies we have going here.

Thank you. Cheers!

thabaum commented 7 months ago

closing this unless someone wants it re opened as completed and continuous work in progress as discussed in meetings. only issue now that should be logged separately is the logo changing from black/white in light/dark theme modes.