Using different repos because their docs always load within the main project, in an editable docs folder.
They used to rebuild the docs every 30 mins - now they have triggers that initiate automatic rebuild of the docs every time there’s a change.
Anybody has to be able to contribute to the docs. They can get their exact setup for this. Everything is in the UI: edit in place, ask for merge request - much easier for non-technical persons, although it could be made even more simple.
They now rely on the writers to use the correct spelling and grammar checker they can work into their editor - but they need a consistent way to do it without each writer’s setup. Planning to include spell check into their linters.
Every process goes into the handbook, almost everything is open.
Challenge: how to support all versions of the docs? The gitlab versions locally installed have their own docs with them. In beta now: hosting all versions’ documentation on gitlab docs and having them searchable - without confusing the users. Still to solve version-tagging towards search engines.
* structure: not nest things too deep
* keep single topics
* suggestion: show context to help users’ orientation
* tutorials and guides: flatten as much as possible to the base topic and simplify. Put the existing software hierarchy into a TOC and then try to flatten.
Stunning (API) Docs == + appealing appearance + content structure + clear instructions + proper & consistent gramm… https://t.co/U7ITSOAh8j