A Node by Any Other Name
Joe walks us through Drupal's idiosyncratic naming conventions!
07.12.2016 Technology and Innovation
Anyone who works on team-based projects knows how handy good project documentation is, and how frustrating it can be when that documentation is out of date, incomplete, or just not there. But there are other benefits to good documentation aside from convenience, and a solid system for writing and maintaining documentation is the key.
Before we begin, we should be clear about what we mean when we say ‘Project Documentation’ (Docs for short). We’re referring to the information for team members (developers, designers, project managers, and engineers) who join a project at some point after initial development has begun, or even long after a project is complete, such as a maintenance team. This is different than User/Tech docs (how things work on a site), and Code docs (Comments, README files, etc.).
Good docs allow these team members to get up to speed on a project with a minimum of questions for existing or previous team members. In an ideal world, docs alone would suffice in getting someone set up and working on new features, bugfixes, or other project tasks.
The convenience of good docs is apparent to anyone who joins a project after it has begun, but consider some of the other benefits:
Having your docs in one place, or in the same place on every project is the first step in making them easy to find - after all, what good are the docs if nobody can find them? ThinkShout uses GitHub for all of its projects, so we take advantage of the fact that every project on GitHub has a free Wiki. A link in the README.md to the wiki means everyone can find the docs in seconds.
The keys to good docs are consistency, accuracy, and completeness:
For our Wiki, we have a template we use for every project’s docs, so we don’t have to search for the information among 40 different documentation styles. Your project’s needs may differ, but this should be a good starting point (this is in Markdown):
## Current Status (Site Type / Status. Drupal, WordPress, under development, maintenance, etc...) ## Site Build Info * [Wireframes](URL) * [Budget](URL) * [Implementation overview](URL) * [Migration Spreadsheet](URL) * [Style Guide](URL) ## Build Team * Name (Team Lead) * Name (Back-end) * Name (Front-end) * Name (PM) * Name (Design/UX) ## Hosting * [Dev](URL) * [Test](URL) * [Live](URL) ## Issue Tracking [Redbooth Tasks](URL) ## Deploying Code Note: it is a good practice to run backups before deploying. `cd ~/projects/PROJECTAME;git pull;./scripts/deploy.sh` ## Installation Notes Clone into `projects` folder, install to `~/Sites/`: cd ~/projects git clone email@example.com:thinkshout/PROJECTNAME.git cd PROJECTNAME composer update ./scripts/build.sh ~/Sites/PROJECTNAME root root PROJECTNAME Download db and files from [production](production backup URL) Install the db by opening Sequel Pro, deleting the PROJECTNAME db, adding a new PROJECTNAME db, and importing the live db, then truncating all of the cache_* tables. Install the files by unzipping the file download and copying them to `~/Sites/PROJECTNAME/sites/default/files`, then run: chmod -R 777 ~/Sites/PROJECTNAME/sites/default/files drush cc all drush fra -y Log in: drush uli Disable cache and JS/CSS file aggregation at http://PROJECTNAME.dev/admin/config/development/performance ## Front-end Setup Theme directory is at: `~/Sites/PROJECTNAME/profiles/PROJECTNAME/themes/custom/PROJECTNAME` To get Sass running, `cd` to that directory and run `bundle` Thereafter, you only need to run `rake serve` from the theme directory.
The nice thing about having your docs in a wiki is that everyone in your organization can edit them if they discover they are out of date. When a new team member is added to a project, encourage them to work from the docs and see how far they can get without asking for clarification or dealing with an unexpected error. And make sure they update the docs to reflect their experience - the only time docs are ‘done’ is when anyone can use them reliably every time. If you have to ask what something means, it’s likely that the next person will need to know that too - so update the docs!
Every project has its quirks and exceptions to the standard procedures - usually for good reason. Good docs will not only note exceptions to standard procedures, but also explain why. In addition, sometimes a ‘Phase 2’ project will require additional information. Make note of these major updates with details such as planning info, principals, dates, and an overview of what was accomplished.
Sometimes a developer will run across coding environment issues that hold them up - this is quite common for the complex front-end setups needed to compile SASS into CSS. Front-end developers sometimes take these setups for granted, but documenting that install process can mean that your back-end developer can handle small CSS changes without assistance:
To get Sass running, `cd` to that directory and run `bundle` Thereafter, you only need to run `rake serve` from the theme directory. NOTE: If you get a 'not found' error after running `bundle`, run `gem install bundler`, then `bundle install`.
Finally, it’s not enough to have all of these wonderful docs in place and forgotten - they have to be a part of your project setup and launch checklist, and it needs to a part of every project, big or small.
Consistent, accurate, and complete project documentation will save time, make your code easier to maintain, improve team confidence, and do a great service to every developer who comes to your project after it’s finished. Docs Rocks!
Questions? Comments? We want to know! Drop us a line and let’s start talking.Learn More
Drupal's paragraphs module can be used to make child pages automatically by using custom entity routes.