Thread Rating:
  • 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
New Help System
#1
So I've started working on a new help system. This will be an ongoing thing to actually get the content in place (a lot of it will just be conversion from other sources into this one, integrated, format, but still a lot of work.) It is all based on XML files and a tool I wrote to compile the info together and apply whatever formatting and layout I want to it, dealing with the creation of indices and such. It's getting fairly slick at this point.

I've gotten a sample amount of real help info into it now, so I figured I'd post it for comment. I think it'll be a huge step forward, and will (ASAP) replace the technical documents, the existing 'external content' page and probably the videos as well, at least the detailed ones. I'm sure we'll keep some 'show off features' type of videos.

Here is a link to it:

http://www.charmedquark.com/Web2/CQCDocs/CQCDocs.html

Let me know what you think. The format is always the same, sort of stolen from the MS MSDN format. There are links on the left and content on the right. There are usually two sets of links. The first ones are pages for the current topic, and just load the selected topic page to the right side. The next set are sub-topics that take you to another topic page with its own set of links.

So it's consistent and easy to understand, and it makes it feasible to manage the content without writing a bodacious amount of code or making it too complex to write the stuff.

Where it makes sense, I'm using a lot more images and will also be including examples once I get into things like actions, CML, etc...


Though it's sort of strange writing this help with zero interactive visible feedback, i.e. it's all just text files. OTOH, it's sort of freeing. It don't have to worry about an HTML editor forever making mistakes and munging my stuff, or having to deal with making sure CSS styles are used correctly, or trying to remember how to remain consistent in style or visual style usage. The XML is purely at a high semantic level, and the program converts it to HTML with appropriate ids and classes and other markup. The XML parser really watches my back and makes sure everything is legal, which is a huge benefit over HTML.

Current things not working:

1. I'm not attempting to hook the browser back button into my dynamic loading of content into DIVs. But every page has a back arrow link at the top left to take you back.

2. The links that are inside the right hand text pages are supposed to be (almost all of them) sort of 'quick popup window' links, but I've not implemented those yet, so they probably won't do anything. Or they'll just open up some basic text in another tab.

3. I'll also end up adding some main menu options, where I'll compile a big nested, collapsible topic index to make it easier to find things, and possibly some other stuff. But that's not there now.
Dean Roddey
Explorans limites defectum
Reply
#2
I'll just tell you what I think . No point sugar coating it Wink

Don't like it. Feels very old school.
--Kill all the serial ports--
Reply
#3
bbrendon Wrote:Don't like it. Feels very old school.

In what way? It's pretty much a rip off of MS's MSDN sort of look. It has the simple, basic color scheme of so much stuff these days. And of course it is just help, not an application or anything. Not that help can't be a little fancy, but presumably it's mostly about just getting the information laid out in a way that's easy to access and whatnot.
Dean Roddey
Explorans limites defectum
Reply
#4
Some descent examples...

http://ceph.com/docs/master/install/

https://confluence.atlassian.com/display...ation+Home

I was on one I liked a few weeks ago but can't recall what it was.

...It doesn't have to be awesome like you said. As long as I can goto google and type in "site:chardmedquark.com <whatever>" And easily find what I want I'm happy Smile
--Kill all the serial ports--
Reply
#5
Some good guiding examples from bbrendon but overall I do really like the idea Dean. Keep writing it as if it's for a child audience and it will be a great help in pushing out your product.

Jim
Reply
#6
I very much like the idea of consolidated documentation, and I think it looks very clean and easy to read. One question comes to mind though - do you still plan on making a downloadable PDF version available? I continue to find the PDF documentation invaluable as I work on bringing myself up to speed (and also for reference later).
Reply
#7
There wouldn't be a PDF version, since it would be generated from XML documents. Unless we used some PDF creation library or something to do it.
Dean Roddey
Explorans limites defectum
Reply
#8
I figured that might be the case. While the PDF would be missed, I suspect the XML-generated documentation would be much easier to create and maintain on your end, and would probably greatly help in keeping it up-to-date.
Reply
#9
I really like it. Clean, clear, and w/pictures. What's not to like. Easy on the eyes. Oh and it's XML generated. Moving forward.

If you want a .pdf you can easily print directly to file in Chrome.
Reply


Possibly Related Threads...
Thread Author Replies Views Last Post
  System Config Interface need DaveB 5 3,639 04-12-2017, 02:29 AM
Last Post: DaveB
  Bringing system up to date? RobWalker 16 6,868 06-11-2014, 03:27 AM
Last Post: RobWalker

Forum Jump:


Users browsing this thread: 1 Guest(s)