Open abhishekluv opened 9 years ago
@rtpHarry Hi. I have created list of issues which are to be fixed. Please share your issues here so that we can work and fix them together.
This document got pretty long, pretty fast haha. I have been collecting these thoughts together recently but I hadn't posted them publicly yet because I wanted to have a clear idea of the situation and also to calm down a bit so I didn't run off getting all excited and implement things that aren't a priority for right now. So here are my thoughts:
Yes, I from reviewing this I had many of them in my mind. The project is so huge and complex I have been taking some time to form a proper plan before I got serious.
First off, I don't want to disparage the work that that has already been done. There is a lot of great groundwork thats been written in this site and it got me started when I first wanted to learn about Orchard. But as the project has been going for over 6 years now some of the docs have inevitably got out of date.
I had been noticing things like you have said in your list above but I was thinking it needs some core structural improvements first. The way I see it, as each version (I think v1.9.x is enough) comes out we need a completely new branch of the site. The old documentation shouldn't disappear for users that haven't updated. The steps below go into more detail but basically I want to:
~/Documentation/Pre-v1.9/
folder~/Documentation/v1.9/
folderI don't think we should rush into it though as there is some important groundwork we should do before getting started.
~/Attachments
and ~/Uploads
) and when combined should be stored within ~/Documentation/Images/
folder so it can be duplicated each time.Initial ideas for columns:
Orchard.LearnOrchard.SampleName
namespaceThere is an open issue about this, it seems it was discussed at the last Harvest to split it out into userdocs.orchardproject.net and docs.orchardproject.net. Personally I would keep docs here for the users and move everything else into developers.orchardproject.net as that seems more standard but thats just a detail.
I think with all the other work taking this on at the moment would be too much so thats why I'm suggesting it as future plans.
My initial view on this is that there are three types of users out there:
Since reading through the existing docs I have seen this idea already in peoples minds but just using different names.
Because of the awesome power of Orchard we really need to document many things twice as they can be done either by a Website developer via the admin panel or by an Orchard developer via code. When tutorials match up there should be a notice box at the top with the concept of "you can also do this via the (admin panel|source code)".
One of the complexities of this is the multiple install options. Each user type has a likely install path. We should make opinionated recommendations within the articles about how you should be installing Orchard based on which level of user we are targeting.
An internal checklist needs creating for managing new releases.
This is just scratching the surface. The ideas in here are mostly just being formed and we will need to flesh out the ideas before major work can begin.
To move forward I think an initial round of reactions here and then maybe start splitting these things out into individual Issues to get down to the details. We have milestones and tags at our disposal as well which can organise this.
What happened to this? I am new to Orchard and am going on a deep dive and already found at least 3 places where the docs are really out of date or just straight up wrong. I'd love to dig in and help but its hard to know where the best place to start is? Should I just make PR's on specific peices of content? For example this:
https://github.com/OrchardCMS/OrchardDoc/blob/master/docs/Documentation/Writing-a-new-theme.markdown
Is really old in that the files created by codegen are not what the tutorial actually says. Happy to fix just don't want to waste my time if there is a process that I'm missing.
This is a very casual repo. I don't think anyone is working on anything, there hasn't been any real activity for a long time. If you spot something you want to contribute to then go for it!
If its a big documentation that will take you a while and you don't want to clash then you can open it as a separate issue or just say you are working on it in this thread just so anyone else starting out is in the loop.
Lists of OrchadDoc Issues to be fixed.