PHP Developers Network

A community of PHP developers offering assistance, advice, discussion, and friendship.
 
Loading
It is currently Sat Oct 19, 2019 2:59 pm

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 
Offline
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 http://www.phpdoc.org/ 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!


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

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

_________________
(#10850)


Top
 Profile  
 
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 1 guest


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