Replies: 2 comments 2 replies
-
|
@thabaum I mentioned this in the Developer Meeting last week.... Microsoft is no longer using DoxFX for their documentation (they are now using a dynamic approach ie. a CMS). The DocFX project was transferred from Microsoft to the .NET Foundation last year. https://github.com/dotnet/DocFX/ "As you may have heard docfx has been transitioned to be a .NET Foundation project. Microsoft Learn no longer uses docfx and do not intend to support the project since Nov 2022." dotnet-foundation/projects#257 "DocFX was a core tool used to create all the pages published to docs.microsoft.com – however we’ve since shifted to a more dynamic rendering model and our dependency on this site generator has been reduced to just the parsing code. As such, the primary engineering team responsible for Learn is no longer contributing formally to this project, but we recognize that there are a lot of other teams and customers using this tool, so we'd like to keep expanding it's use for the community. As such, we’ll create an announcement of shifting the project to a contributor-maintained model under the .NET Foundation umbrella where it will continue to evolve and be supported by the existing maintainers that are still passionate about its development." |
Beta Was this translation helpful? Give feedback.
-
|
@sbwalker I see this is what they are using to show the documentation, which actually aligns more with the idea of it all I had years back for DNN. We should follow what Microsoft has done. I dont know where we will find a CMS for this... joking :). i believe we should create some form of a documentation that follows the lead, but it still looks like they use GitHub. Just using a CMS to make the pages. Our HTML module can do this currently... which then points to a GitHub page, I know this because I have contributed to it in the past. I was wondering how they got away from this. I would need examples of what they are using instead of GitHub. DocFX is just a website... nothing more. Oqtane CMS can handle this! The questions then are:
Then the Wiki, Forums (more than one if we like GitHub and Site forums) and GitHub pages can be linked from these resources including the static HTML. This project would be a great one to push the limits of Oqtane SSR static rendering potential and benchmarks. The issue in developer meetings and other sources with current docs is dealing with GitHub markup I believe as well. This is why some preferred something like Live Writer to contribute. Well maybe we need a "Learn.oqtane.org" that showcases all the sources of community driven support and tutorials relating to Oqtane. Try to make it look like Microsoft Learn following it's lead in our own way if that makes sense? It would be the same as following the Microsoft architecture in a way, and I think this new approach Microsoft uses is going to be most familiar to anyone lighting up Oqtane. I see the end game for them created an easier way for others to contribute. We no longer need to learn docfx, just GitHub markup. I think in the terms of "dogfooding" we would use the docfx project to strip down pages. Then those pages can be updated by everyone and used by DocFX community members to update that. Maybe DocFX can produce a release that excludes the other pages. I have a feeling this is going to get old and a CMS/GitHub Repository combination is going to do the trick after reviewing things. We can leave both, but just link to the new source pages created in the Oqtane.Docs GitHub repository and link the API to docfx for the auto-generation? This is a bit confusing to discuss in chat a bit. What I feel is if Oqtane DocFX version 5.2 can be updated to latest info as a release package that excludes the Oqtane.Docs Learn.Oqtane.org links and then go on their own from there for those using or wishing to help maintain as it is still .NET Foundation. This way it is not a breaking change for anyone and helps that part of Oqtane family with ways to update the docs from resources being more easily contributed to. Or should we look into some other way to document the API. After reviewing Microsoft Learn if you go to the developer section it uses DocFX still. The user administration docs resources not related to development such as the API could stay on Oqtane.Docs and Oqtane.Learn be gauged more for easier contributions using only GitHub, Blogs and other resources linked as shown in my proposal for an idea to think about. Microsoft has a dotnet-api-docs GitHub repository, maybe we should do the same? The best idea I had from all of this is creating a |
Beta Was this translation helpful? Give feedback.
-
|
It looks to me like Microsoft is still using DocFX, just not supporting it as it has probably matured past needing it or is there some other solution they are using to display and maintain their docs? Different sections from Microsoft Learn seem to go to a lot of different projects that include docfx repos. So I am guessing teams are still using it, just MS is not directly supporting DocFX.
This was what I was thinking would of been a good plan is to use DocFX for the code parsing but I am not 100% sure what all that means. It still feels like they are reliant on DocFX but it has matured past a point of needing to spend time working on this one feature since it is rock solid and still being used?! Just trying to digest all the issues and discussions of the past to produce some ideas worth trying to see if worth going forward with. I really like the Oqtane Learn site idea or something of this nature to help connect with each community powered resource dedicated to Oqtane. We can also review the Microsoft Documentation Contribution repo for some ideas to improve ours upon or maybe create one to separate concerns for the different groups of maintainers? Anyhow I think we should really research some ideas that give a very similar feel to how Microsoft does things but with our own community twists if that makes sense. I am just now taking all this in over the last week as I never really paid attention to docs prior, and I am totally new to DocFX. From some additional research worth mentioning. Here are the locations for docs used by Microsoft currently, but this can change obviously. and many other places in Microsoft Learn direct you towards many "DocFX" community powered resources. |
Beta Was this translation helpful? Give feedback.
-
|
My 2cents Setting up DocFx is difficult - but to be honest it's actually getting easier, now that MS isn't the main lead any more. There is a lot of momentum in the project so I feel like it's going in a very good direction. Since the setup is already done (and now up to .net 8 / latest theme) I don't see any good reason to switch in the near future. The docs part is markdown, which is something most developers got used to so here too there is little to nag. It may feel like a step backwards, but in reality (from ca. 5+ years of documenting https://docs.2sxc.org/ the benefits of having a simple setup with statically rendered pages (which host for free on github with little technical challenges etc.) and the clean versioning / attribution of changes makes it the best system I can think of for this job. There are so many benefits like the ability to simply archive an older version (again on a static host, with zero mentainenace) - eg. https://v16.docs.2sxc.org/ and more, + the ability for users to fork it, contribute, and push suggestions. For now, I really don't see a system that would be better - unless we would invest 1000+ hours into development. And as of now, I strongly urge to invest such 1000+ hours into docs-content or anything else, and not re-invent the wheel. |
Beta Was this translation helpful? Give feedback.
-
DocFX Open Source Community Project
It would be nice to see some help wanted and number of tickets open like shown here on our readme.
I believe our documentation should follow how Microsoft creates theirs if possible but I have found nothing out about what they are currently using yet. When looking for ways to structure our pages content we should make them look like Microsoft's as much as possible.
This project is still .NET Foundation which is the same as Oqtane. I think it is still worthy of supporting as we can. A lot of search links go to this info...
When looking for way to structure our pages we should make them look like Microsofts as much as possible.
They man not be using it, but they have to be using something connected to GitHub.
My guess is they rewrote DocFX maybe in Blazor and put together an easier interface to submit and manage documentation and inclusion of different types of resources but could not introduce breaking changes or did not want to share this advancement to community so forked away. I will be investigating this further see if I can find out more. Any additional information or feedback here is welcome.
Cheers!
Beta Was this translation helpful? Give feedback.
All reactions