# Many documentation upgrades, using AsciiDoctor as our primary way to write documentation, Michalis thoughts and plans about our documentation **URL:** https://forum.castle-engine.io/t/many-documentation-upgrades-using-asciidoctor-as-our-primary-way-to-write-documentation-michalis-thoughts-and-plans-about-our-documentation/486 **Category:** News **Created:** [December 31, 2021, 6:05pm UTC](https://forum.castle-engine.io/t/many-documentation-upgrades-using-asciidoctor-as-our-primary-way-to-write-documentation-michalis-thoughts-and-plans-about-our-documentation/486 "2021-12-31T18:05:03Z") **Posts on this page:** 1 **Page:** 1
### Author: ![michalis](https://forum.castle-engine.io/user_avatar/forum.castle-engine.io/michalis/32/3_2.png) [@michalis](https://forum.castle-engine.io/u/michalis) #### Post date: [December 31, 2021, 6:05pm UTC](https://forum.castle-engine.io/t/many-documentation-upgrades-using-asciidoctor-as-our-primary-way-to-write-documentation-michalis-thoughts-and-plans-about-our-documentation/486/1 "2021-12-31T18:05:03Z")
| [![CGE website](https://castle-engine.io/wp/wp-content/uploads/2021/12/Zrzut-ekranu-z-2021-12-30-07-47-36-200x146.png)](https://castle-engine.io/wp/wp-content/uploads/2021/12/Zrzut-ekranu-z-2021-12-30-07-47-36.png "CGE website") | | [![CGE website](https://castle-engine.io/wp/wp-content/uploads/2021/12/Zrzut-ekranu-z-2021-12-30-07-47-17-200x126.png)](https://castle-engine.io/wp/wp-content/uploads/2021/12/Zrzut-ekranu-z-2021-12-30-07-47-17.png "CGE website") | ## Documentation upgrades done lately Lots of documentation (in particular from wiki) was reworked, simplified, updated, consolidated with other pages… See in particular: - [Build Tool](https://castle-engine.io/build_tool) - [CastleEngineManifest.xml – Syntax and Examples](https://castle-engine.io/project_manifest) - [Android Services](https://castle-engine.io/android_services) (each particular service now has a dedicated documentation page) - [iOS Services](https://castle-engine.io/ios_services) (each particular service now has a dedicated documentation page) - [glTF](https://castle-engine.io/gltf) - [Sprite sheets](https://castle-engine.io/sprite_sheets) - [Coding conventions](https://castle-engine.io/coding_conventions) - Lots of new pages are now linked from [documentation sidebar](https://castle-engine.io/documentation.php). Browse them! 🙂 We converted 100% of our [GitHub wiki](https://github.com/castle-engine/castle-engine/wiki/) contents to AsciiDoctor. This was done using [kramdown-asciidoc](https://github.com/asciidoctor/kramdown-asciidoc) and lots of manual tweaking. Resulting [AsciiDoctor sources are here](https://github.com/castle-engine/cge-www/tree/master/htdocs/doc). Editing them is trivial, and the HTMLs are auto-regenerated when updating the website. Note also the text _To improve this documentation just edit the source of this page in AsciiDoctor (simple wiki-like syntax)…._ at the bottom of new pages, with ready links to edit each page! We have pretty URLs for pages generated by AsciiDoctor. So now we have [https://castle-engine.io/build\_tool](https://castle-engine.io/build_tool) instead of previous [https://github.com/castle-engine/castle-engine/wiki/Build-Tool](https://github.com/castle-engine/castle-engine/wiki/Build-Tool). We also have nicer “404 not found” page now, try it: [https://castle-engine.io/not\_existing](https://castle-engine.io/not_existing). ## Why? I was thinking lately of updates to our documentation. They come down to 2 big things: 1. 2. Lots of manual updates, to document the fact that you can (and should, in simple cases) do many of the basic things using the editor. E.g. current manual describes usage of `TCastleScene` from code (and disregarding typical cross-platform app organization, that we advise). It should instead describe using TCastleScene from editor, _and from code too_, and placing most stuff in TUIState instances. ## Thoughts: Various approaches to documentation I used a number of approaches for online documentation throughout my life, and within CGE. - DocBook (e.g. for [compositing shaders (to both HTML and PDF)](https://castle-engine.io/compositing_shaders_doc/html/), my Ph.D thesis), - LaTeX (e.g. for [shadow maps](https://castle-engine.io/shadow_maps_x3d.pdf) paper). - AsciiDoctor: I used this for [modern Pascal introduction](https://castle-engine.io/modern_pascal_introduction.html), [sources on GitHub](https://github.com/michaliskambi/modern-pascal-introduction/). - Jekyll (I used it for [PasDoc](https://pasdoc.github.io/) website): - [News using WordPress](https://castle-engine.io/wp/): WordPress is good, esp. I like - [GitHub wiki](https://github.com/castle-engine/castle-engine/wiki/): - [Our website using hand-crafted PHP with theme based on Bootstrap](https://castle-engine.io/), which is our current main way to write website: We need to make improvements: 1. This can be extension of current PHP code. 2. easy shortcode to add API docs. 3. One markup, comfortable. Also replace GitHub wiki with it. I hope you find these thoughts useful 🙂 These plans have been followed by actions — see section _Documentation upgrades done lately_ above. _Please support the engine development on [our Patreon](https://www.patreon.com/castleengine). It funds development of the engine, including the efforts to document it perfectly._