@anmhuicin Starting a topic here to chat about possible documentation styles we could use on the project. It would be great if we could settle on a clear style and “voice” to make all our docs approachable and consistent for users.
1 Like
The Python Crash Course is the book I always recommend to people learning Python. It’s really well designed and the writing is clear, concise and very approachable.
If I had to pick one reference for our documentation style, it’d be this one. You can download a sample chapter on their website.
This is my favourite technical book of all time. He explains one of the most complex areas of computer science (language compiler design) with a lovely quirky style and clear explanations. He hand drew and hand lettered every single diagram and cartoon in the book - incredible.
I think this style might be a little too quirky for our needs though. It could be hard to keep the style consistent when people are contributing to the documentation. Still, I love how he uses humour to make the learning process fun and engaging.
The Godot Docs look to be very well organized and the writing style is simple and clear. Much better than the Unity & Unreal docs IMO. The Getting Started section has a clear focus on first time users, while the Manual section provides detail for more experienced users. I really like the single page layout, very easy to navigate and explore. They’re hosted on Read the Docs.com
I’m also a big fan of the Godot docs. One thing Unity has that they lack, though, is a good annotation system, plus a glossary:
It would be cool to incorporate something like this into the Celbridge docs.
Yeah annotations would be very useful. I see the Godot docs are generated using the Sphinx — Sphinx documentation Python library. I’ll check if it supports annotations.
@anmhuicin Looks like Sphinx has good built-in support for glossaries, Add a Glossary — RST | Sphinx | Sublime | GitHub documentation
There’s also an extension that might work for displaying tooltips on hover Welcome to sphinx-hoverxref! — sphinx-hoverxref documentation
1 Like
btw, Sphinx uses the reStructuredText (reST) format for writing documentation, for example all of Godot’s docs are written using reST. We could use Markdown instead of reST via the MyST python package, apparently it works very well.
Just looking through the Godot docs, they have excellent content and writing guidelines: Writing documentation — Godot Engine (stable) documentation in English
I think these would be a great starting point for our own docs?
This is great! I’ve also been looking at the Google Documentation Style Guide; I took their self-paced Technical Writing course last week. There’s a lot of great stuff in the voice and tone section about how to prioritise clarity and avoid cognitive load:
Yup, that looks very useful 
I’ve just got Myst working - so all docs .md now except top level index.rst with nav info
- the problem before was underscores and hyphens
- not in requirements.txt as I originally through, but it was a mis-match between page anchors (created with hypens) and references to them (created with underscores) when I used the * * rst2md to batch convert RST files to Markdown
- (note to self - raise this as an issue for that OSS project if I can reproduce it - but not working now on my Mac …)
- so I’ve changed all page anchors to be with underscores
as far as I can see it works with no errors in Github actions
- but if anyone can check a few pages for links / images that would be great (I quickly flicked through every page and they appear fine to me)
so - docs content same as before but now as Myst Markdown instead of RST 
.. matt ..