Take the 2-minute tour ×
WordPress Development Stack Exchange is a question and answer site for WordPress developers and administrators. It's 100% free, no registration required.

We have been creating a bunch of templates that are very custom and change from time to time but also have a bunch of similar parts from theme to theme. I am looking to streamline the way we create our documentation to pass off to users and was looking to the WPA community to see what they use for creating docs. I was thinking of creating sometype of Wiki to pass along to clients that we would build upon as we go but is not completely clear to me yet on how to do so.

Can anyone share their experiences, trials, tribulations?

Thanks in advance!

JN

share|improve this question
    
You should def. answer more Qs- 60% accept rate is too low... –  kaiser Sep 6 '11 at 22:22
add comment

closed as not constructive by Rarst Oct 22 '12 at 19:08

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.If this question can be reworded to fit the rules in the help center, please edit the question.

1 Answer

Great question. There is no generic and comprehensive documentation workflow in WordPress circles. However there are some nice tools and options to make use of.

readme.txt

Markdown-based machine-readable file. It's main purpose is to be parsed and presented by official plugin repository, but it's not too convenient outside of that.

It is great and fitting place for initial overview, but not so much for advanced instructions.

Contextual help

Contextual help in administration panels had just recently (relatively) started to become useful. Great place for UI instructions, links to local and remote resources and maybe short FAQ.

Major issue that being new and underused thing it probably won't occur to users to look there for information. Easy workaround is to trigger it open conditionally - for example on first time or until user performs required operations (setting up configuration, etc).

PHPDoc

Inline documentation is essential for developers. Makes it easy to learn or maintain code. Very useful in IDEs.

A little less obvious aspect is that with some effort inline documentation can be used as source to generate more human-friendly docs. Typical example are cross-references, but there are a lot of less common possibilities to explore like generating wiki pages (shameless plug).

Non-WP-specific tools

Other than what WP and PHP offer there is obviously ton of other things you can do, depending on your and your clients' needs.

Typical out-of-WP solutions used are wikis (or just sites with docs), issue trackers, hosted community support services, etc.

Also there had been some exploration into mixing extensive documentation in WP itself. In simplest case this can be just including rich readme.html with plugin. But there are also more complex possibilities, like using of custom post types for docs.

share|improve this answer
    
Thank you @Rarst +1 to you. This all is very valuable information and greatly appreciated. Something that has worked for us in the past has been to create Video tutorials for each theme and give the client a walkthrough on each video. I like the idea of creating some type of documentation per theme that is directly accessible within the admin and having an html doc with some embedded videos, etc. The wp-help plugin seems very close to the lines of what I am thinking. I will post some answers as I explore this more. Sweet plugin btw and thanks again! –  jnolte Sep 7 '11 at 20:19
add comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.