How do you document your MODx sites?

We shortly came about the question what documentation duties you have as a web designer in respect to your clients. As far as classic software design is concerned certain things are defined, as a lawyer and IT prof told me.

Web design may not be the same as classical software design, but it comes close and I’d like to document for me, the client and possible third parties a modx web site:
- which templates used for which pages
- which custom TV’s in which templates
- which and where custom snippets, chunks, plugins, modules and their role / tasks
- users, usergroups and their roles and rights
- additional software and functions
- etc.

So do you have some excel sheets or other stuff prepared for this? In the ManagerManager there are some basic details given (templates, TVs and roles) but not very connected.

Before starting my own documentation project ... I thought I ask you all. Thanks for any hints and ideas!

I sometimes create a text area template variable and assign it to all templates. In there I can document or even leave simple instructions for my customers.

This is a good question. Hopefully others will chime in here...

Thanks for the HelpManager links, hadn’t seen that before. It’s a great addition to the manager.

I still think there should be a written version for the customer (beyond the standard Editor Documentation) and also for any developer (maybe PHP pro but MODx Newbie) that has to take over a site. As it’s an advantage of MODx that as a customer you are not bound to "Typo3"-style rare and expensive agencies this should be a concern.

What I’m doing mostly is a documentation where I put the manager editing screen of a document and the page in the frontend along side by side and create lines pointing to what input is resulting in what output and where.

But sometimes when I go back to a project after some weeks I’d like to have an overview for myself which page is using which template, which template which TV’s etc. Maybe this can done by writing some clever SQL requests over the MODx db, maybe I look into that...

In the latest versions of MODx, the built-in Help can be added to simply by creating files in the assets/templates/help directory.

Tabs are automatically generated, using the file name for the tab title. Underscores in the filename are replaced by spaces in the tab title, and tab order is determined by the leading number in the filename.

See the default 01Help_Overview.php file for the default layout and styling; of course you can set it up any way you like, since it’s displayed in the Manager’s "main" frame.

I usually add an icon link to the Help feature in the main Manager welcome page, along with the other icon links, since the Manager’s Help link is just the little one up in the upper right corner.

Documentation is sooooo important, yet soooo neglected. I appreciate all the billable hours resulting from crawling through other people’s spaghetti mess, but it’s such a shame that developers either aren’t paid to provide docs or that they simply don’t do it enough. I try to put my money where my mouth is: I’ve authored a fair number of the pages on the MODx wiki, so allow me to make the following recommendations:

• DO NOT TRY TO BE CLEVER; Strive for Simplicity Strive for implementations that are so logical that they don’t need much documentation. Clever code is fun only if you’re drunk with the CompSci majors. Dealing with somebody else’s "clever" code is usually a nightmare. If you do something that differs substantially from the expected norm, this should be a flaming red flag. Ask yourself why are you going against years of experience to do something "different"? Is there another way to do it that would take approximately the same amount of effort but be more understandable? Sometimes, a clever solution is best, but if that’s the route you take, ALWAYS make some comments so others can follow your brilliance in the months to come.
• Put your documentation where people need it. This is what comments are all about. You’ll notice on your bathroom faucet, the tap says which knob is for hot and which one is for cold. The labels for the faucets are not on the refrigerator. Provide the same type of courtesy with naming your variables, functions, chunks etc. This is why I love the ability to extend the help contents in the latest versions of MODx.
• Define the Inputs/Outputs of your functions. This is key to the concept of reusable code... you don’t have to understand any of the code inside of a function if you know how to send it values and get values back. It’s such a waste to have to read through every function in someone’s library to figure out what it is and what in needs as input.
• Create a README file. Personally, I like to create a README file as an unpublished document in my MODx sites. That way it’s right there if anyone needs it, and inside of it I can put any notes about anything that’s weird or unique about the site, I can list important files, I can include links to wiki pages or ticketing software, or put in my contact info etc. It’s right there where the manager users can find it.

I have some reservations about extensive documentation in snippet, module and plugin code (what goes into the Manager fields). These are inserted into the siteCache.idx.php cache file so that the parser can access them without additional database queries. Then these are all loaded into arrays in memory. But when there are hundreds of lines of comments in this code, it bloats the cache file, not to mention the memory arrays in use during parsing. Quite a few of the more commonly used snippets, for example, have several times the number of lines of documentation and comments as they do actual PHP code.

It seems to me that it would be better to have the comments and other documentation in a text file in the appropriate assets directory and have the code in the Manager (and thus the database and the cache file) as clean and brief as possible. The text file (definitely NOT with a .php extension) could be a heavily commented version of the php code, along with other supporting documentation.

I agree with you for a high-profile site, Susan, but for most of the smaller sites I’d rather have some comments and documentation somewhere so people knew what was going on in the code before worrying about optimizing cache. I’d settle for a read-me file, but the problem is that many new developers do a poor job of documenting. You can fix caching... you can buy more bandwidth and RAM, but you can’t make documentation appear out of nowhere.

i like the idea of leaving instructions to the customers. And too clever hiding info actions are not good either.

Nice discussion and some great advice! I love the idea of the help manager and also of the readme file, where I could collect all the instructions I send to the customers by mail from time to time.

Today for a smaller project we ended up in two spreadsheets - one that lists document ids, their titles and the templates used, the other listing the templates, the TV’s, snippets and chunks in use. That’s not totally complete of course. But when I come back to the project in some weeks for new content that will help me to get productive faster.

I still think if this could not be done by some sql queries and nice php output, maybe I try something sooner or later...