I launched a new startup / open source product. http://bookingbat.com/ It is online appointment scheduling software (shameless plug).
I need to create a user guide. In the past, for my other project "Vehicle Fits" I created an HTML user guide. This collection of HTML files was checked into version control so it stays in sync with the particular version of software its describing.
I feel that that solution fell short. The 'documentation' link on my website takes the user "away" from my website into this ugly HTML frame (see http://vehiclefits.com). For this new project I want to be able to have the user guide on my website, within the header & footer of my website. However my website is stored in a separate repository from my application.
I know Zend Framwork uses 'doc book' which is an XML format. It gets converted into HTML, and someone could write a script to pull that HTML into their website, while keeping the doc book XML itself in version control.
But also it seems like 'mark down' is getting popular, partially thanks to GitHub.
So basically my question is how can I create a user guide that can easily be included in my website, but also stored in a different repository than my website?
Writing a user guide
Moderator: General Moderators
Re: Writing a user guide
It kinda depends how you want it integrated with the website. Are you talking about just linking to particular parts of the guide (from within the header/footer and according to the current page) or something more complex?
Re: Writing a user guide
Something more complex. I think I figured out one way. Zend Framework does it like this. They generate the HTML with table of contents (TOC) using their tool (sphinx docs). Then they add a MVC controller which accepts a GET parameter "page", it then looks for the HTML file that matches that "page" param. Then it uses an xpath query (with Zend\Dom component) to grab the body & TOC into different variables & render those in a new template.
I also found this cool tool that converts from markdown into docbook XML, which can then be in turn converted into individual HTML files with a table of contents on each page: https://github.com/jgm/pandoc see the example: http://johnmacfarlane.net/pandoc/demo/example9/
With something like that example9 I could pull the TOC into a sidebar on every page then use XPATH to grab the next/prev links, etc.. and render them into a custom template.
This is kind of a roundabout way but its the easiest way to achieve what I want that I know of as of now. For an example of the end-product see ZF docs:
http://framework.zend.com/manual/2.2/en/index.html
http://framework.zend.com/manual/2.2/en ... start.html
See how the table of contents in the sidebar "drills down" as you go deeper in the hierarchy? I want that effect without having to tediously update links when they change, etc..
I also found this cool tool that converts from markdown into docbook XML, which can then be in turn converted into individual HTML files with a table of contents on each page: https://github.com/jgm/pandoc see the example: http://johnmacfarlane.net/pandoc/demo/example9/
With something like that example9 I could pull the TOC into a sidebar on every page then use XPATH to grab the next/prev links, etc.. and render them into a custom template.
This is kind of a roundabout way but its the easiest way to achieve what I want that I know of as of now. For an example of the end-product see ZF docs:
http://framework.zend.com/manual/2.2/en/index.html
http://framework.zend.com/manual/2.2/en ... start.html
See how the table of contents in the sidebar "drills down" as you go deeper in the hierarchy? I want that effect without having to tediously update links when they change, etc..
Re: Writing a user guide
Then a database of sorts (traditional or a file) is definitely the way to go. If you needed to update or edit the text manually then a database would be better, but if you're using something that will automatically generate the text based on something (like code documentation) you won't need to do any editing and a file or set of files is easy to deal with.
Docbook is nice. It's just XML so you can do whatever you want to read from it if you can get your source material into that format. Showing that ToC on the left is basically just a function to list whatever sections are at a location, with some recursion when there's nesting.
If you want to get fancy you can use XSLT, via XSLTProcessor (requires enabling an extension), to automatically turn the XML into HTML. It can literally be a matter of setting "parameters" and rendering the XSLT; the XSLT is what does all the work, and lends itself to recursion more naturally than procedural languages like PHP.
Docbook is nice. It's just XML so you can do whatever you want to read from it if you can get your source material into that format. Showing that ToC on the left is basically just a function to list whatever sections are at a location, with some recursion when there's nesting.
If you want to get fancy you can use XSLT, via XSLTProcessor (requires enabling an extension), to automatically turn the XML into HTML. It can literally be a matter of setting "parameters" and rendering the XSLT; the XSLT is what does all the work, and lends itself to recursion more naturally than procedural languages like PHP.
Re: Writing a user guide
Idea look great..when will this up?
Re: Writing a user guide
The docbook or sphinx tools already convert to HTML. That's the whole point of using them over HTML, they automatically generate the ToC so you don't have to write any code. I want to write documentation for my project, not create my own documentation generator...requinix wrote: automatically turn the XML into HTML
Re: Writing a user guide
Yes, but the tools won't integrate that HTML with your website. Right? Isn't that the problem you're trying to solve?
I'm not telling you to make your own documentation generator. What I am telling you is how you could use the source XML to put elements, like links to the generated HTML, in your web pages.
I'm not telling you to make your own documentation generator. What I am telling you is how you could use the source XML to put elements, like links to the generated HTML, in your web pages.
Re: Writing a user guide
Ok I understand now. Not sure if XSLT can remove the <html> tag, etc.. since the document I want to pull the documentation into already has it's own (its dynamically generated with an MVC framework). I think the Zend DOM Query is more elegant than XSLT anyways (I just need to grab a div and everything inside of it, and output it, which DOM Query does very simply with a CSS selector like '.contents'). So the issue about taking a boilerplate HTML and pulling it into my MVC website is answered. But, I still haven't decided on what tool I'll use to generate the static HTML though. I've shortlisted pandoc & sphinx-docs