Documentation for Expand (perhaps using ReadTheDocs.org)

[sheldmandu]

Expand Framework is a fantastic project which really supercharges the core DevExpress XAF product and adds many much-needed and commonly used features, BUT the biggest challenge with it is adoption is difficult due to a lack of good documentation. To understand some of the features the only option is to experiment, play with the demos, read the code or read some previously written posts on how the features were built (rather than what they actually do).

Documentation is absolutely crucial to uptake and particularly when there are many competing products developers will often go with those that are well documented and have a vibrant community around them (IoC injectors are a good example). One of the reason Autofac is so popular is it's documentation is exceptional.

It seems more and more projects are now using ReadTheDocs.org to publish their docs with the documentation itself stored and source controlled in github. Some examples include Autofac, SimpleInjector, Hangfire and many others.

My suggestion for a "feature" is to allocate appropriate resources to put in a serious effort into documentation of eXpand as that's what's HUGELY lacking for the project. I would also suggest adopting ReadTheDocs.org for publishing the documentation.

It doesn't matter how fantastic a project is and how awesome the features of a product are if it's hard to understand and adopt due to lack of documentation the project suffers. I truly believe that by refocusing for a short period of time to properly document the existing features in an easy-to-use format Expand Framework will reap benefits far greater than from addition of new features (often without accompanying doco).

I would expect that once the core structure of documentation is put in, most of the documentation can be split by module and would be relatively easy to divide and conquer.

I would even suggest that perhaps a good option may be to get some university students who need to do work experience or a project as part of their degree to get involved in this.

[emeyke]

I'll just add my 2 c on this. DX uses DocFx for end user documentation which is an important block of, well, end user documentation of a xaf based product. I am only exploring the integration and building the documentation and would be interested xpand and xaf community opinions. It does sound somewhat natural to me to build Xpand docs on the same platform as DX EUD, but I am ready to hear your suggestions for alternatives.

Currently my initial trial looks like this: https://earthcape.com/docs which builds on DX end user foundation: https://github.com/DevExpress/dotnet-eud

[sheldmandu]

DocFx seems more like an API documentation generator rather than a platform for maintaining functional documentation. What I'm suggesting is to improve uptake of expand (even by existing users) it would be extremely beneficial to have some sort of half decent documentation. Some of the features in expand are simple, while some others are quite complex and it would be nice to know what they are and how they work from an user (i.e. developer as a user) perspective rather than how they were built. I know there are some nice features like view inheritence, etc there, that would be really nice, but last time I looked at them they either didn't work or were too hard to understand so I just gave up.

[apobekiaris]

Expand Framework is a fantastic project which really supercharges the core DevExpress XAF product and adds many much-needed and commonly used features, BUT the biggest challenge with it is adoption is difficult due to a lack of good documentation. To understand some of the features the only option is to experiment, play with the demos, read the code or read some previously written posts on how the features were built (rather than what they actually do). Documentation is absolutely crucial to uptake and particularly when there are many competing products developers will often go with those that are well documented and have a vibrant community around them (IoC injectors are a good example). One of the reason Autofac is so popular is it's documentation is exceptional.

I totally agreed and the work is in progress, I am sure you noticed it the https://github.com/eXpandFramework/DevExpress.XAF modules are fully documented fully tested with simple functional tests. Interested for you feedback on that project as well. What do you feel that the existing doc there? can you follow those modules given their docs?

It seems more and more projects are now using ReadTheDocs.org to publish their docs with the documentation itself stored and source controlled in github. Some examples include Autofac, SimpleInjector, Hangfire and many others.

at the moment I have not decide if I integrate ReadTheDocs. Many projects have them I agree also many project do not use them except the initial documentation they added once. I am not sure whyis that but there should be a reason. Said this and since DevExpress.XAF modules will be fully documented having a searchable/editable wiki here in GitHub I do not think I need more resources on this, (p.s. feel free to contribute to existing readme with PR so you can credited the work in your GitHub profile.

Finally my plan is to evolve docs for this community and not using tools for other audiences without first to have a clear demand for them.

So plan is to grow a momentum here where GitHub which is familiar to most than switching at least for the moment.

Feel free to contribute and let the demand drive us.

[sheldmandu]

Hi @apobekiaris No, I havn't seen the documentation in the DevExpress.XAF modules. I think that level of documention is indeed sufficient as it describes what the functionality does and how it works. I agree that if you feel github is sufficient there is no point in introducing yet another platform for documentation.

I guess the question is what are the chance of getting some documentation around all the existing modules within Expand as there are so many. I know it's not the most exciting writing documentation, but from experience, besides making sure that the features actually work and are relative bug free and with good issue resolution when they arise, documentation is the next most important thing for uptake.

Even if you could create the skeleton pages, I'd be happy to add descriptions to some of the features of expand I use on a regular basis, although that's probably just a small portion of all of expand features.

[apobekiaris]

documentation is a contract and we cannot have such a contract as the main framework does not have unit tests and although EasyTests are really powerfull and might be used they hard to support and they do not help in code design. For a documentation contract there should be a clear bridge to the source code tests.

The focus is on xaf.expandframework.com which the structure is clear.

1. The module creates signals out of events combinations
2. It performs ac action for each signal
3. It output signals for further processing

check out this skeleton here autocommit.expandframework.com or here http://suppressconfirmation.expandframework.com

check the unit tests to see how close are to the docs.

If you wish to help building around this idea and improving it further you most welcome. the main framework current architecture is totally outdated. for compatibility reason and for containerization it has a value however we should proceed in more flexible and stable architecture.

My plans are to package all major parts of the main app. There is also https://github.com/eXpandFramework/XpandPosh which is really powerfull in a world of nugets and does not have docs.

having a small percentage of this idea working I see the end user being able to:

1. I am working on a master-detail scenarion on XAF, hmm let's see whats on Xpand and he enters in a powershell prompt. (Having XpandPosh installed.)

Find-XpandPackage master

Name                           Version          Source           Summary
----                           -------          ------           -------
eXpandMasterDetailWin          18.2.703         NuGet3           MasterDetail Module (Win) / eXpandFramework
eXpandMasterDetail             18.2.703         NuGet3           MasterDetail Module / eXpandFramework
Xpand.XAF.Modules.MasterDetail 0.0.10           NuGet3           The `MasterDetail` module can help you create platform agnostic master detail `XAF` views using only the Model Editor.

Now he knows which packages where the docs how they work.

[sheldmandu]

Yes, it's all very neat and will be great when it's up and working, but what I'm saying is it's a real struggle to know what Expand has and even more of a struggle to understand how it works once you find that it has it. I mean even with a multitude of controllers and property editors that do little handy things there isn't a great deal of documentation atm which makes it a real struggle.

[apobekiaris]

your comment is not constructive though. I already answered about the solution to this problem, a proof of work with 6 modules is already out and more coming fast. So use and contribute to that project if you want to lose the black box weight.

[sheldmandu]

Btw, I had a look and I agree that splitting functionality into their own little modules with good documentation is definitely the way to go. Then users can pick what they need / want and don't have to get the whole XpandSystemModule with everything in it. It's kind of the same idea / logic as what in PHP world ZendFramework did between ZF2 and ZF3.

[apobekiaris]

• package managment from the Xpanposh so you can be fast in all basic modifications

say you have a problem with the model and you suspect one of the xpand modules then

Find-XpandPackage Model|Uninstall-Package

to uninstall all and see if the problem persists.

[expand]

Closing issue for age. Feel free to reopen it at any time.

.Thank you for your contribution.