PHP Developers Network

A community of PHP developers offering assistance, advice, discussion, and friendship.
It is currently Tue Jul 07, 2020 11:12 am

All times are UTC - 5 hours

Post new topic Reply to topic  [ 2 posts ] 
Author Message
 Post subject: Documentation Advice
PostPosted: Sat Sep 08, 2012 1:21 pm 
Forum Newbie

Joined: Mon Feb 07, 2011 4:36 am
Posts: 20
I'm still a relatively new developer, but I'm reaching the point in my work that I'm starting to understand the importance of documentation. I've started to create my own documentation application, but it feels like this is something that someone has probably already done far better than I could do. Without blabbering on too much, here's what I'm thinking...

I'm looking for a solution that is simple, and lightweight. I've seen things like but I'm not sure this is what I want. Applications like this seem to take the "auto documentation" approach which is absolutely awesome! But that's not really what I want (plus I need to document more than just php). I really want to be able to describe my features, use cases, classes, methods, etc... in a more flexible way. I want to be detailed where it seems important, and broad where it doesn't. My goal is to create lightweight docs that will be primarily for myself, the few developers that I work with, and/or someone that might come behind me to work on a project.

The possible solutions I've considered so far...

I could just create pdfs. Lightweight and highly custom, but not very enjoyable to use. And just being real with myself, if it's not a pleasure to use, it will not get much attention. Also, it hurts me a little to think about creating a lot of static data. Who knows what else I would want to do with it, but I'd like it to be in a format that I could expand upon in the future.

I could create static html pages. Similar pros and cons to the pdfs, with the exception that reading the documentation might be more satisfying (design, navigation etc...).

I could create my own application. The benefits here are obvious. It could be anything I want it to be... But there are only so many hours in the day :) and I'm not sure this is something that I should be spending time on. This is what I'm leaning towards, but again, it feels like a mistake.

I could create a wordpress theme for documenting. This is very appealing in that I could lean on wordpress to do a lot of the heavy lifting (potential user management, commenting, the list goes on and on), while still creating something that could be highly custom. It would also be something that I could share with other developers as a simple documentation tool, and the time invested in creating the theme would feel a lot more worth it if it would be something that other developers could make use of.

Having said all that, I guess I'm just really anxious to hear how you all handle documentation. Am I missing something obvious?

Any advice or input is greatly appreciated!

 Post subject: Re: Documentation Advice
PostPosted: Sat Sep 08, 2012 10:30 pm 
Site Administrator
User avatar

Joined: Wed Aug 25, 2004 7:54 pm
Posts: 13592
Location: New York, NY, US


Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 2 posts ] 

All times are UTC - 5 hours

Who is online

Users browsing this forum: No registered users and 13 guests

You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Jump to:  
Powered by phpBB® Forum Software © phpBB Group