This project is read-only.

Documentation and the new Orchard web site design

Topics: Announcements
Nov 13, 2014 at 8:19 PM
I was wondering how the Orchard documentation will fit into the new web site design - will it be a continuation and rebranding of the current documentation web site project, or are bigger things planned?

The reason I ask is that I have developed a module that could be of benefit. I designed it to basically allow me to re-use and customize documentation amongst multiple clients, but with a few tweaks I'm realizing it could be much more - basically it could be the core of a help documentation "ecosystem" for the larger Orchard community.

The vision:
  1. Integrate context-sensitive help into your Orchard admin console: click on a help link and you'll see help for the console page that you're on. By default the help content is served from a central community-provided source.
  2. If you want, you can also host and use your own help service. With that you can:
  3. Document your own modules, including console pages and individual fields. You do this by deploying markdown files in a special folder in an Orchard module (this is one approach, the code can be extended to import/synchronize from any source).
  4. Document other people's modules.
  5. Download and install others' documentation - e.g. imagine 'standard Orchard' documentation packages.
  6. Display documentation within your own site and theme.
  7. Provide localized versions of topics and reference items.
  8. Add Orchard-version-specific notes for topics.
  9. Document how one module may change the behavior of another module.
  10. Attach content parts to your help documentation (help items are content items). For example, you can associate help content with blog items or other pages.
  11. Publish not only to your site, but to other formats like a flat markdown file, suitable for ebook generation. I've tested this with pandoc and have created epubs already.
The module is about 90% there in terms of the above vision, at least as far as the code goes.

Would the Orchard community be interested in something like this?

If so, I could deploy a sample site complete with documentation on how it all works. It would be much easier to see it action than it would be to describe it all here. I could probably even import a bit of the current Orchard documentation to see how it would look.

Thank you, I'm looking forward to your feedback!

Nov 14, 2014 at 2:48 AM
It would be great to see your module in action on a demo site, because I am not 100% sure I get what you mean ;)
Nov 16, 2014 at 6:08 PM
No problem! I'll create a demo site and import some documentation into it, and post back onto this thread when it's up and running.
Nov 16, 2014 at 9:47 PM
You can watch some integration tests made by Shaun Luttin:

I think I will also try to help more with this in a near future.
Nov 30, 2014 at 7:25 PM
I've deployed a demo site to:

The site includes documentation on how to use the module, as well as for authoring help.

There's also some "forward-looking statements" in the docs regarding one way the help system could be used for hosting community documentation. The wording is mostly to present some ideas, and see if the module could be used for the Orchard documentation efforts (and if so, get creative input and direction to refine it for that purpose).
Nov 30, 2014 at 8:05 PM
Edited Nov 30, 2014 at 8:07 PM
Very interesting project! I'll check it out.

Do you have something in mind for developer documentation?

FYI viewing issues on the BB project page is denied for non-members.
Dec 1, 2014 at 7:09 AM
This looks great.
Just started reading how it works.
One question.
One thing I always wanted to do to help end users is to be able to provide for my content types (eg page, projection, etc) a help link specific to that content type instance.
For example ideally there would be a Help Part that could be attached to an existing content type definition (example the projection content type).
Then for every projection instance I create (or reports as i call them) in the admin editor the author will provide documentation for that report (what it does, how its used , show screenshots etc).
Then on the front side viewing this report will render a help link (similar to widget wrappers that show the edit link) that will direct user to a page in the help documentation.
This will auto update so when the report author adds or changes the documentation from the admin the help site will update its content automatically.
So your documentation pages are always up to date.
Its kind of similar to client side libraries (like dgeni) when you change the help source and a grunt task updates the help page automatically.
Can such a scenario be covered with this module?

Dec 1, 2014 at 8:27 AM
Thanks Zoltán, I've fixed the BB issues permissions.

I think Admin Help would be able to handle a whole set of documents, including a User's Guide and books for developers, designers and installers/IT. The User's Guide would probably be the one with context-sensitive help in Orchard and would probably be the highest priority.

One thing I'm wary of is that I don't want to divide documentation efforts for Orchard. Admin Help could be a candidate to host the 'standard' Orchard docs, and I'd like to try a port of those docs, but only if it doesn't interfere with what others are doing or planning.
Dec 1, 2014 at 8:56 AM
Hi giannik,

Regarding the first part of your question, yes you can document custom content types. The content type is part of the data sent to the help service, and the help service translates that into a help context that you can reference in your help documentation.

For the second part, Admin Help is intended for admin console (backend) users. For front-end help it's probably easier for you to add a content link field to the projection type, and for each projection instance, set the content link field to a page that describes your report.
Dec 3, 2014 at 5:28 PM
This is really cool!!.
Just tried it out.
Great work brentbysouth.
Very well thought out and very Orchardy in the way it works.
I would love to this this baked in as a core module.
I think it would also be useful if integrated with the gallery so info about each persons module is grabbed from help sections defined in the module itself.
Thanks again.
Feb 3, 2015 at 11:19 AM

On the site how do you implement the right side bar navigation menu to filter
based on the topics . Is it a custom module or tweaking the menu widget in some way?
Feb 5, 2015 at 5:35 PM
Hi giannik,

This was one thing I wasn't too happy about doing as it didn't seem clean. The filter logic is in the theme:

The code is in /views/Menu-secondary-menu.cshtml.

Hope this helps,
Feb 5, 2015 at 7:19 PM
I added a menu alternate with template you mentioned and it worked.
Thank you, Brent.