Improved documentation

[Moult]

Description of the proposal:

This is not a schema change, so it may be off-topic, but I believe this is still incredibly important to ensure a continued adoption of standards by developers... so the proposal is to improve the visuals and usability of the IFC documentation. It might sound superficial and not very technical, but I strongly believe this will have a huge impact on IFC.

In concrete terms, this means:

• Use a standard doc generation system that doesn't rely on Windows-only tools like IfcDoc, and ideally is completely plaintext and follows well established doc generation best practices in the software world. This means stuff like generation from Markdown, rst (or other humanish flavour, not XML), CLI generation apps, etc. I think as devs have read the spec we've all come across things which don't quite make sense, but the process to get changes into the docs is prohibitive to us contributing these changes.
• Hire a web designer to take a look at it and choose some colours, make it responsive, clearer font sizes, nicer typefaces, etc. Just a bit of CSS would make it so much more appealing and more modern.
• A search feature would be nice. Like, really nice. So many people are using https://blenderbim.org/search-ifc-class.html because the official docs lack a search feature.
• Fix the HTML compliance. I tried parsing the HTML docs, and there's a lot of broken markup.
• More IFC (STEP/XML/JSON?) examples, and check that the examples actually work.
• Stuff that is useful to developers like one-liner descriptions of IFC classes should be also converted into a computer interpretable format so that devs can easily include them in apps, such as in tooltips to help users.
• Get a technical writer and diagram maker to help restructure the "fundamental concepts and assumptions" page to make it so that if you read it like a book, you'd understand as a newcomer how IFC works. It should also cover concepts which seem to be missing or not very well described there like materials vs styles.
• Link to code examples! I'm not talking STEP, I mean actual code. You know how popular dev libs always have "let's get started, here's a library to use in this language, that language, and here's 5 lines of code to generate your first IFC file" - that's what developers love! Here's a viewer you can use to debug your file, etc.
• Use more real project examples in the docs. It took good while for me to understand things like "if we label a wall construction type as WT01 on paper docs, which IFC attribute does this belong to?". More real life data usage in IFC examples would be very, very beneficial.

OSArch is happy to help out with this process, or even lead this initiative.

OSArch has some WIP articles on describing IFC to newcomers, which may help:

• https://wiki.osarch.org/index.php?title=Industry_Foundation_Class_(IFC)
• https://wiki.osarch.org/index.php?title=IFC_classes
• https://wiki.osarch.org/index.php?title=IFC_projects_and_contexts
• https://wiki.osarch.org/index.php?title=IFC_attributes_and_properties
• https://wiki.osarch.org/index.php?title=IFC_spatial_tree
• https://wiki.osarch.org/index.php?title=IFC_materials
• https://wiki.osarch.org/index.php?title=IFC_geolocation
• https://wiki.osarch.org/index.php?title=IFC_aggregates
• https://wiki.osarch.org/index.php?title=IFC_classifications

[agviegas]

This is critical. In my opinion (as someone coding applications based on IFC) , this is one of the main reasons why it is so hard to find developers who are / want to get into IFC.

[Jesusbill]

A big +1 for this proposal. I have been using the official documentation for more than a year now and only today I found out that some text in the various pages is actually a clickable link, like for example the Attribute Inheritance table. This dialog actually took place today in OSArch chat room :)

[berlotti]

Progress..... http://ifc43-docs.standards.buildingsmart.org/

[Moult]

@berlotti awesome! Is it accepting user contributions? I see an unmerged PR from November last year. I had no idea that project existed!

Exciting times ahead!

I realised I didn't mention mobile-friendly in the OP, but that would be cool too.

[berlotti]

Projects are using other sources to write their documentation, so there is a risk of running out of sync. After projects have delivered their results, these pages (https://github.com/buildingSMART/IFC4.3.x-development/tree/master/docs) will be used to update/maintain IFC 4.3.x and community contributions are very welcome.

We are very open to contributions on the script that generates this. So feel free to make the pages responsive / mobile friendly if you want :-)

[Moult]

We are very open to contributions on the script that generates this.

@berlotti isn't there a script which already exists? Otherwise what is generating this?

[aothms]

I just realized the code repo is already public https://github.com/AECgeeks/ifc43-documentation-server but we should probably move it to the bSI organization or something. Also the code is probably not in a very readable state.

[berlotti]

Now available on https://github.com/buildingSMART/IFC4.3.x-development