CodeIgniter Forums

Full Version: what is the best workflow to write documntation ?
You're currently viewing a stripped down version of our content. View the full version with proper formatting.

El Forum

[eluser]Blaze Boy[/eluser]
i want to write a documentation for a project with the same style or codeigniter manual and DMZ manual and formgeneration library manual ...
what is the best workflow i have to follow to write it ?
thanks guys in advance

El Forum

[eluser]Craig A Rodway[/eluser]
Any good?

El Forum

[eluser]Colin Williams[/eluser]
I typically sketch out my code as sort of an abstract class, and maybe map out the API/workflow in pencil and paper if its complexity necessitates it. Then I take that and start writing the documentation--yes, before completing the code. The documentation basically becomes a road map for development. They grow and change side by side. Sometime what you planned has to change for technical reasons, and other times it becomes unnecessarily difficult to explain the API, so you change the API to make it more simple.

El Forum

[eluser]Blaze Boy[/eluser]
[quote author="Colin Williams" date="1262494453"]I typically sketch out my code as sort of an abstract class, and maybe map out the API/workflow in pencil and paper if its complexity necessitates it. Then I take that and start writing the documentation--yes, before completing the code. The documentation basically becomes a road map for development. They grow and change side by side. Sometime what you planned has to change for technical reasons, and other times it becomes unnecessarily difficult to explain the API, so you change the API to make it more simple.[/quote]
thanks colin,
i can see your way in writing the docs , but the problem is ... i take alot of time writing the same page title over and over in the page ... a lot of time to format the page ,, any programs would facilitate the way i can write the docs ?

El Forum

[eluser]Colin Williams[/eluser]
I would suggest a CMS. Drupal is my favorite.

El Forum

[eluser]Johan André[/eluser]
I would go for spending good time in designing your stylesheet which holds all elements (headlines, paragraphs, imagefloats). When you are happy with it - just head over to a good wysiwyg-editor and write the docs and apply all the styles you defined. Dreamweaver would be my choice here. I only use it for this purpose.

El Forum

[eluser]m4rw3r[/eluser]
If you want something more rigid and standardized, look at DocBook.

It is XML based and contains a huge set of tags for different purposes. The large number of tags may seem daunting at first, but it gets easier once you've learned the basic ones (one downside is that you will probably have to search for the correct tag sometimes).

Styling it should be quite straightforward, but it will be harder to change the HTML structure as it uses a XSLT stylesheet to convert the xml to html (or PDF, man pages, whatever).

If you want to take a look at a project I've written which uses docbook, look at RapidDataMapper. The xml sources are in doc/manual/src.

El Forum

[eluser]Blaze Boy[/eluser]
thanks johan andre , i think dreamweaver would be enough for me ..
m4rw3r, i think the XML solution is time killing and consuming

El Forum

[eluser]The Hamburgler[/eluser]
I've been working on a CI application to generate my user guides which I run on my local dev server.

I code all my pages as separate view files, including just the content HTML. I then use a config file to hold the user guide variables like name, author and a navigation array.

I can export the user guide from the application which will generate a static HTML user guide zip which will add the header and footer to each page.

I've stayed pretty close the the CI user guide template mentioned earlier. Seems to be working pretty well so far. I hope to have it posted soon, PM me if you want to try it out.