-
Notifications
You must be signed in to change notification settings - Fork 74
Home
Welcome to the GovCMS developer wiki. This is a community maintained wiki which is curated by the GovCMS team at the Department of Finance. The goal is to use clear language, useful overviews, and supplement this with links to other resources.
Important: this documentation is currently being re-written, and some sections may be incomplete or incorrect. If something doesn't make sense or is plain wrong, either fix it or lodge an issue so it can be addressed for everyone. Items marked with '@TODO' may already exist somewhere in this guide, but might need re-writing.
During 2019, you can contact Simon Hobbs if there are serious issues with accuracy or structure in the documentation.
- What this guide is for
- Wiki/Documentation principles
- Get started: What do you want to do
- Migrating content from READMEs
What you can find here
- A overview of the various systems that form govCMS
- @TODO: A detailed technical breakdown of how govCMS works, aimed mainly at developers
- @TODO: Clear examples of how to use it on Windows, Linux and Mac OS
- @TODO: A clear guide to start developing your own projects with it, including setting up local development sites
- @TODO: Troubleshooting information for common issues
What you won't find here
- The documentation of the various open-source projets that govCMS uses, like Docker, Lagoon, Ahoy, Kubernetes etc. This isn't a replacement or duplicate of their doco, but we do include links to where some of it lives
- Sales information relating to the govCMS offerings - see the govCMS website for that stuff.
Good doco saves lives. Here's how you can help make this resource useful for everyone:
- Anyone can update it. If you know the answer, share the answer! We'd share it with you. Likewise, if something doesn't work or make sense, edit the page or lodge an issue so everyone is aware of it.
- Write for where the developers are. If you're reading this, it's probably because you either want to understand how govCMS works, start using it, or got stuck using it and need help. Everyone has different levels of experience and knowledge, and often work with different software and operating systems. Assume they're not using yours.
- Don't just talk. Show. Include thorough, realistic examples of things in action wherever possible. Basically the polar opposite of Git's doco.
- Provide copy-paste-ready samples. This lets everyone get on with it with minimal friction, and lets users see it work as intended.
- Include reminders whenever it's relevant. Don't rely on users remembering specific details from other docos. If something matters, mention it. Balance duplication with the right time and place.
- Write for Drupal 8 first. Drupal 7 will be officially End Of Life (EOL) in November 2021. This doesn't mean neglect Drupal 7, but do consider if your contributions will still make sense when D7 is not longer supported.
- When using acronyms, include the full text at least once on each page. Seriously, why the face (wtf)?
- If a page is getting long, include a Table of Contents (TOC) or 'On this page' list. This lets users quickly scan the page and get to the relevant bits faster.
- Try to use existing top-level sections. Consider where your changes will fit into the bigger picture - do they relate to existing sections, or are they significant enough to warrant another?.
- Perhaps most importantly, get it peer reviewed! Ask someone unfamiliar with it to read it and see if it makes sense. When including examples or instructions, always ask someone to try and follow them from start to finish - you'd be amazed what can get missed.
Where practical, please use http://asciiflow.com to draw diagrams.
Feel free to use the Scratchpad for incoming material or questions.
-
I want to learn what govCMS is and how it works
Better start with the 'How it works' section of the govCMS website, then come back here for greater detail.
-
I want to build a new website using govCMS
If you're comfortable you understand how govCMS works, read over the Developer Guide for how to get a project started.
-
I have an existing website, and want to...
-
migrate it into govCMS SaaS
@TODO: link to forklift process?
-
migrate it into govCMS PaaS
@TODO: link to migration process
-
-
I'm already using govCMS to host my website, but got stuck and need help!
There's a few places you can go:
- Check out the Developer Guide, in particular the Known issues and workarounds section
- See if someone else has already encountered your issue, and if a solution has been found
- If you're a SaaS/PaaS customer, you can lodge a support ticket.
-
I'm managing a project that uses govCMS, and want to know more about governance and security
@TODO: Here's where to get information about govCMS's security
It is currently hard to update documentation when it's stored in READMEs in git repos. Pull requests and code reviews aren't needed for instructions. Additionally, docs are being duplicated via the use of scaffolds and such. The plan is to move how-to's out of READMEs and into this wiki, and make some other wikis redundant.
During 2019, you can contact Simon Hobbs if there are serious issues with accuracy or structure in the documentation.
List of READMEs in scope:
| Project | Docs | Plan |
|---|---|---|
| govCMS/govcms8_uikit_starter | readme, no wiki | No change |
| govCMS/govcms | readme | rationalise README, Wiki is this wiki |
| govCMS/govcms8 | readme, wiki | rationalise README, Wiki already merged |
| govCMS/govcms7-scaffold | readme, no wiki | rationalise README |
| govCMS/govcms7-scaffold-paas | readme, no wiki | rationalise README |
| govCMS/govcms8-scaffold | readme, no wiki | rationalise README |
| govCMS/govcms8-scaffold-paas | readme, no wiki | rationalise README |
| govCMS/govcmslagoon | readme, no wiki | No plan |
| govCMS/govcms8lagoon | readma, no wiki | No plan |