Lists of OrchardDoc Issues to be fixed

[abhishekluv]

Lists of OrchadDoc Issues to be fixed.

• Creating-a-module-with-a-simple-text-editor : needs an update
• Building a hello world module : needs an update
• Writing a content part : needs an update
• Upgrading a site to a new version of Orchard : needs an update
• Themes includes : needs an update or delete it
• Themes : needs an update or delete it
• Testplan : needs an update or delete it
• test : delete this page
• Templates : old aspx stuffs here
• Template file syntax guide : old stuff lets see what can we do here.
• Template files and their locations : old stuff lets see what can we do here.
• tags : delete this page
• Source-code-organization : lets see what can we do here
• Slugs : delete this page
• Setup : needs an update
• Setting-up-a-source-enlistment : needs an update
• Setting up a multi tenant Orchard site : needs an update
• Previewing-and-applying-a-theme : needs an update
• Pages : delete this page
• Pages-Editing : delete this page
• Using the command line interface : needs an update
• Orchard Markup Guidelines : needs an update
• Orchard dependencies and libraries : needs an update
• Navigation : delete this page
• Merging-Pull-Requests : needs an update
• Installing Orchard Using Web PI : delete this page
• How Orchard works : needs an update
• Developer-FAQ : lets improve this
• Creating a custom field type : needs an update
• Basic Orchard Concepts : needs an update
• Accessing-and-rendering-shapes : table rendering issue

[abhishekluv]

@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.

[rtpHarry]

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:

• Group all current docs into a ~/Documentation/Pre-v1.9/ folder
• Clone the entire docs into a ~/Documentation/v1.9/ folder
• Set up a url rewrite system so vLatest always stays in the main location like everything currently is (don't break links)
• Add a version switcher to the right col of site
• At the moment leave the Pre-v1.9 as the vLatest and add a BETA banner saying v1.9 docs are being worked on.

I don't think we should rush into it though as there is some important groundwork we should do before getting started.

Pre-Overhaul Steps

1. Build a tool that will parse the markdown for broken links, orphaned images. With the aim to create an authoritative list of articles in the repo
2. Get all of the images into the same folder structure (currently in ~/Attachments and ~/Uploads) and when combined should be stored within ~/Documentation/Images/ folder so it can be duplicated each time.
3. Produce a shared spreadsheet to track progress which lists all every .markdown file. Ideas for columns listed in section below.
4. Produce a "documentation standards" document which is a quality checklist before we add it in. Ideas in section below.
5. Syntax highlighting. I haven't looked into this in too much detail yet but initial research I'm thinking change the markdown parser to one that supports github flavoured markdown (GFM), get the snippets wrapped in guarded code blocks with the language encoded into it, use HighlightJS to clean it up.
6. Build an intelligent 404 page - On 404 check same url in each previous version branch and show a custom message like "this document has doesn't exist for vXX the last version this topic was covered is link to last version"
7. Community comments via Disqus. I saw this almost made it in before but then got scrapped for some reason. I think it needs resurrecting.

Documentation Standards

• Screenshots should be made with Share-X or similar tool and have proper formatted highlight boxes / annotations, not hand scrawled Snipping Tool circles
• If it's an API document then it should be more technical like "module developers should...", if it's a tutorial then language can be more familiar like "then we add in..."
• Headings should be second level and below
• Add any url changes to a 301 document (such as renaming an article)
• Check code samples use correct namespace

Spreadsheet tracking all .markdown files for review

Initial ideas for columns:

• Is the file orphaned?
• Is it ready to be archived?
• Is it user manual, developer or both?
• Has the namespace been standardised?
• Has the tutorial been tested on v1.9?
• Has the download been updated?
• Does it need new screenshots making?

The main overhaul

• Implement all the docs updates in the spreadsheet
• Get all code samples under a Orchard.LearnOrchard.SampleName namespace
• Create repos for each code sample hosted within the main OrchardCMS github account (I haven't used it but there is an option to give control of a repo to another account, so new contributors can still make their own repo and then hand it over later without needing access to main OrchardCMS github)
• Cull the out of date content - There is stuff that is so out of date it's not even funny. There are sections that are in there that compare Orchard to Oxite (which was discontinued 6 years ago) and many of the videos are targeting v1.1.

Medium term plans

• Start adding new documentation to the project
• Create a spreadsheet that lists every module and its documentation status
• Each week run a promotion on a specific module in the chatroom to get experts to either contribute article ideas or actual articles
• There should be an API section with documentation of the codebase
• There should be a "press pack" section with the official logo and a brand information
• Current documents should be sifted out into multiple documents when they cover user manual and developer topics in the same file

Long term future plans - split the whole thing into 2 or 3 docs

There 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:

1. Website administrators - people that only want to use the the admin panel. They want to manage an existing website by posting content. They will install it via the WebPI. They will install the themes and modules and not go any deeper than that. This is essentially a user manual.
2. Website developers - they want to set up new sites, they might do it off the source but they are mainly interested in how to get the site installed, how to make their own theme. They will install it via the source code or via the WebPI. They will use the admin panel to add fields and parts to content types but aren't interested in the source code.
3. Orchard developers - these people go beyond just putting together websites, they delve into the source code to create modules and want to understand the core workings of the site. They will install it via a source enlistment.

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.

Standardise the release process of the actual OrchardCMS project

An internal checklist needs creating for managing new releases.

• There are many places outside of the docs where the site needs to be updated. For example,
  • At the moment the main website still says 1.9.1 is coming soon on the Microsoft Web Application Gallery.
  • Codeplex, although it is being shut down still says 1.8.1 is the latest version.
  • There are links inside various pages of the Orchard website.
• In the run up to the release a new fork of the documentation should be made. Orchard Developers would need to agree on a feature freeze at some point to give docs a stable place to work from. I think this might already be happening.
• Review the commits since last version to produce a hitlist - what needs reviewing, what new docs need adding.
• Send an email out to all gallery contributors saying prepare your modules/themes for the new version
• Work with the global community to make sure their sites are updated

Conclusion

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.

[sethreidnz]

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.

[rtpHarry]

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.