V4.0 Documentation

[mbreckon]

With reference to this issue #708 it is clear that Nigel is going to be stepping back from maintaining Caliburn Micro. I'm a grateful user of the framework and still use it regularly (doing engineering apps in WPF on desktop systems).

The documentation has however been minimal at best and threatens now to be completely out of date.

Nigel has suggested #708 (comment) he is prepared to merge PR requests for documentation (something I'm prepared to contribute some time to) but there is a risk we end up all working on the same thing.

I've opened this issue as a proposal to have a single issue that tracks thoughts on the current documentation and what needs doing.

Approach
We've decided to use this issue to plan and collate all the top-level work that needs to be done for the V4.0.0 documentation. We will then use individual issues in the website repository to discuss the finer details.

Current planned work

• Migrating to v4.0.0

[mbreckon]

See also #634

[nigel-sampson]

Thanks for stepping up here.

[mbreckon]

I don't use Caliburn.Micro across a wide enough set of scenarios (and so far only on 3.2) to take a huge amount on but I'd like to see it continue. Hopefully there will be enough people in the community to work together to take it forward and I'm happy to help out where I can. I've started trying to piece together a list of the key changes from 3.2 to 4.0 so that I can assess gaps in the documentation but if you had a few minutes to simply dump a list in this thread that would be great. I guess the big thing is async support?

[mbreckon]

@KasperSK referencing #708 (comment) I've created this issue to gather together thoughts and specific changes we might want to do to the documentation for V4.0. Please feel free to contribute (see my comment above - this is going to need to be a group effort).

[snalesso]

I really like this project and I use it in every WPF+MVVM project of mine.
I'm pretty sad with the news, and I would like to contribute to the project to see it evolve to async, which I've been waiting for a lot of time.
Problem is I'm not such an expert with threading etc. to feel like I would be able to touch the code, but I would like to know all that needs to be done in details to reflect on what I can be able to do. Time is not a problem for me (at least for some months).

[KasperSK]

Looking at the issues in https://github.com/Caliburn-Micro/Caliburn.Micro/milestones could help with finding the key changes.

I have been developing WPF applications and now I am developing for Xamarin Forms, so I can probably contribute with some input regarding Xamarin Forms usage.

Regarding what changes need to be done I think we should update the getting started portion so that it reflects how to setup a project on each platform. Maybe update the Caliburn.Micro.Start nuget package if it has not been all ready?
A migrating to 4.0.0 section should also be made so that a migration from 3.2.0 is easy, kinda like the existing Migrating to 2.0.0. I also think the focus here should be on the switch to async.

In the 'Soup to Nuts' section over all i think we need to remove references to platform that are no longer supported. I have looked the sections over briefly and added some comments below:

1. Like in the basic configuration section we need to remove references to Silverlight and replace it with a modern example. The basic concepts explained should still be valid.

2. Customizing The Bootstrapper in this section i think we should add how the Bootstrapper works on other platforms. And remove the non relevant parts.

3. All About Actions might be fine I am not sure whether there are differences between desktop platform and mobile platforms? Since there are some differences between WPF Xaml and XF Xaml. From my usage it has worked the same on both platforms but there might be caveats.

4. • 5. Working With Windows Phone and Working with Windows RT sections maybe these should be replaced by sections on platforms like Xamarin Forms and UWP?

5. IResult and Coroutines, I think what is in here is still valid I am not sure if there has been any changes here.

6. Screens, Conductors and Composition, this section looks okay to me but maybe the examples should be looked over.

7. All About Conventions, this section also contains references to unsupported platforms. Other than that i do not think there has been big changes here.

8.1 View / ViewModel Naming Conventions, this section looks good i dont' think conventions has changed.

8.2 Handling Custom Conventions, this section looks good i don't think conventions has changed.

8.3 Using the NameTransformer, this section looks good i don't think conventions has changed.

9. The Event Aggregator, this section need some updating to reflect the new async support and the new subscribe methods.

10. Simple IoC Container, this section looks to be fine and can be reused.

11. Service Locator, this section looks to be fine as well.

12. The Window Manager, this section could use a good write up but it might be for a version 2 of the 4.0.0 docs. Since the window manager differs pr. platform.

13. Design Time Support, this has references to VS2010 and WP7 that can be removed. Is design time support the same on all platforms?

14. Async (Task Support), since there is a lot of async support in 4.0.0 maybe this should be put into the coroutine section.

I think we might also need a section on how the navigation service is used as that is quite useful on mobile platforms.

I don't know if i missed anything but I do think the existing documentation is a good starting point for this.

I think I will focus on the working with Xamarin Forms section that need to be added for a start.

Regarding tracking the work would it be better to do an issue for each section that need a rewrite so the sections can be assigned to avoid dual work? And should we do it in the repo that holds the documentation?

[nigel-sampson]

Regarding the Start package, I had spent a little bit of time in building new templates based off dotnet new. The idea was the setup samples would form the code that became the templates. https://github.com/Caliburn-Micro/Caliburn.Micro/blob/master/scripts/create-templates.ps1

[mbreckon]

I wonder if we risk losing the bigger picture if we move all the documentation discussion to the other repo. What do people think about keeping the discussion here around what to do for a V4.0 doc release and create issues for the specific items in the other repo? I can link the specific items into this issue so we have a record of the discussion in one place. I've not done a lot of open source development on GitHub though so I can imagine that those with experience may know where the pitfalls are.

@KasperSK I think a "Migrating to 4.0.0" section seems good - I think I came across one place recently where I was forced to use async where I hadn't previously had to for example. If we are going to create specific issues in the other repo then that seems like a good starting point - the detail discussion could then happen there.

I've not had a chance to explore the other proposals more than a quick glance (looks good) but will endeavour to comment in detail soon. Hopefully others will feel able to chip in too.

[KasperSK]

@mbreckon I think you are right lets keep the bigger picture in this thread and then make smaller issues for detailed discussion.

I have made an issue regarding the migration to 4.0.0 part of the documentation here: Migrating to 4.0.0 issue

[mbreckon]

Something to make clear in the UWP platform section - namespace syntax! Issue 710

[CoreyVincent]

I would love to help with documentation.
I'm no expert by any means. But perhaps a beginner's eye view can help to make the documentation more friendly to new users?
I know when I first started I was very confused with the documentation.
I am currently using Caliburn.Micro in my WPF apps. And would love to learn more about the inner workings of this framework more.
@mbreckon @KasperSK @vb2ae @nigel-sampson

[KasperSK]

@CoreyVincent I have started to work on the documentation but it is a work in progress, any feedback would be nice.

WIP Version 4.0 Documentation

[CoreyVincent]

@KasperSK great, I'll start taking a look at that and hopefully give some useful feedback.

[vb2ae]

@KasperSK @CoreyVincent @mbreckon Thanks for doing this

[CoreyVincent]

@KasperSK I submitted some suggested changes to the Introduction. Not sure if I did it correctly. Also, where can I place images that go with the document?

[nigel-sampson]

Currently documentation images are stored in https://github.com/Caliburn-Micro/caliburn-micro.github.io/tree/master/public/images/documentation

[KasperSK]

@CoreyVincent did you fork the documentation repository?

[CoreyVincent]

@KasperSK I forked the one that you forked, so that you could pull it into the stuff you already worked on. Though I could just fork the master. Let me know what would be best.
Also, it was the configuration.md, not the introduction.md, though I will probably take a look at that as well, lots of lengthy paragraphs.

[CoreyVincent]

@nigel-sampson @vb2ae Should the Documentation be updated at least to say the project is being maintained again? A lot of people are being turned away from the project seeing that on the homepage of the website.

[KasperSK]

@CoreyVincent Did you push your changes to github?

Edit: Never mind I found your changes.

[vb2ae]

@CoreyVincent yes please

[CoreyVincent]

@KasperSK @nigel-sampson Was that the proper way for me to submit changes? What repo should I be pulling from?

[CoreyVincent]

Also, is there any reason why we don't just switch to a wiki on the github page?

[nigel-sampson]

The other repository is a GitHub pages site powering https://caliburnmicro.com/

PR's merged here will update the website in a few minutes.

[a44281071]

Multi language switch in document page is greet. In this way, I can also contribute.

[vb2ae]

@a44281071 I like the idea. Which languages would you add?

[a44281071]

@vb2ae Chinese language.
However, whether to establish an editing template first, or with the help of some websites.