On June 23rd, 2021, we announced docs.superoffice.com after consolidating content across two community clubs, six stand-alone static websites, and several blog and forum posts. Behind the scenes, the old content was organized in five GitHub repositories: superoffice-docs, database, data-access, crmscript, and user-interface.
Now, we have taken the consolidation one step further and combined these five repos into one: superoffice-docs. This giant refactoring benefits authors and contributors and paves the road for future improvements. The published site is more or less the same (changes listed later in this post).
Why
As we gained experience from working with content tasks on the new site, we noticed some overhead:
- Conceptual information for company, contact, diary, document, project, quote, request, and sale was scattered throughout the five repos.
- Common settings (cspell), templates, and reusable text chunks were duplicated in each repo.
- We had to manage dependencies between repos. If you moved or renamed a file in repo A, you also had to make changes in the other repos to avoid broken links - which meant multiple branches and pull requests that had to be coordinated.
- We lost Git history when we moved content from one repo to another.
- The backlog was fragmented. We had to create an umbrella project and board to track and prioritize all issues in one location.
- The tools and build pipeline had to be aware of all repos and juggle Git submodules. It also added complexity for those who wanted to build the whole site locally.
In addition, it was not always clear where something belonged. Contributors got confused and had to look in multiple repos before finding stuff.
Solution
Essentially, we did a sophisticated Git merge for each repo using a tool called git filter-repo followed by clean-up.
- Grouped how-tos.
- Grouped all downloadable files.
- Got rid of most duplicates.
- Moved all whats-new pages to superoffice-docs/release-notes/.
- Updated all links.
- Updated table-of-contents files (toc.yml).
- Renamed and moved physical folders to match the output URLs.
- Created a new build file, which turned out to be a third of the old one.
The four main graft points are:
- crmscript to superoffice-docs/docs/automation/crmscript/
- database to superoffice-docs/docs/database/
- data-access to superoffice-docs/docs/api/
- user-interface to superoffice-docs/docs/ui/
You can read all about the details in the monorepo GitHub issue.
Practical implications
If you previously cloned or forked the crmscript, database, data-access, or user-interface repo, you need to switch to using the superoffice-docs repo.
The URLs to some API references have changed:
- CRMScript: automation/crmscript/reference/index.html
- Trigger scripts: automation/trigger/reference/index.html
- Webhooks: automation/webhook/reference/index.html
- bLogic screen elements: ui/blogic/reference/index.html
Content about custom fields, udef, user-defined fields, extra fields, and extra tables is grouped under custom-objects/.
The NetServer API options for contact, company, diary, document, project, quote, sale, and request now have /howto/ instead of /api/ in the URL.
The pages of the CRMScript "Working with..." section are now in the above-mentioned API option sections.
In conclusion
We hope you find this useful and interesting! Please let us know what you think by providing feedback on our GitHub discussion board. Go check it out!
Disclaimer: You will need a github account, but the good news is that registration is super simple!