-
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 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 something doesn't work or make sense, edit the page or lodge an issue so everyone is aware of it. If you know the answer, share the answer. We'd share it with you.
- 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 links whenever it's relevant. It's not always enough to link once at the top of the page. Provide the right information whenever contextually appropriate
- 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?
- When using acronyms, include the full text at least once on each page. Seriously, why the face (wtf)?
- 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.
What best describes your situtation?
Better start with the 'How it works' section of the govCMS website, then come back here for greater detail.
If you're comfortable you understand how govCMS works, read over the Developer Guide for how to get a project started.
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.
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 |