Documentation Improvements

[mottosso]

Hi @ocornut,

I'd like to contribute Getting Started documentation for imgui via the imgui wiki.

I've already taken the liberty of refactoring its layout but wanted to check with you whether you would mind or have any preferences on future layout and included documentation.

What I'd like to cover primarily is:

• Build instructions for common compilers, such as cl.exe and clang.
• Minimal, but complete, examples using common window libraries, such as glfw3

And eventually, fully transfer the documentation currently hiding in the source file.

[ocornut]

Hello Marcus and thanks for helping.

Build instructions on common compiler, such as cl.exe and clang.

That would be good, generally anything Getting Started would be good :)

(We can also strive to improve those example as I'm definitively not happy with how they build, but it's not a trivial problem to solve with multi-platform into the equation, lots of devil in the details. I was considering using Premake/Genie to provide easy project creation (and we can afford to embed Genie binaries). CMake is unfortunately really unacceptably messy and confusing.)

Minimal, but complete, examples using common window libraries, such as glfw3

How would that differ from the existing code in examples/opengl_example/ ?
I suppose it wouldn't hurt to have one simplified example on-line.

And eventually, fully transfer the documentation currently hiding in the source file.

We have to look things up on a case by case basis. While it is probably the case most of the time, it isn't always a benefit to remove documentation from the source file. For example, when things changes it can be weird to only have one easily accessible version of the information on-line. So I think it would makes sense to keep simplified version in the code when possible and have fully developed version on the Wiki.

If you are thinking mainly about the "Getting started" a better laid out and complete version on the Wiki would probably be advantageous and then we can clearly link to it from the source code. We just have to be careful with treating those important parts of the Wiki with the same quality as the code, making sure that important links don't break especially if they are linked from different versions of the code, etc.

That said it'd be great if you want to have a go at it and we see how it goes.
There's definitively a lot to do there as ImGui will slowly head into becoming more of a community.

Also maybe have a look at #435
For actual function documentations, I would like them to be generated and that topic has some ideas about it.

[mottosso]

How would that differ from the existing code in examples/opengl_example/ ?

I'm looking for an example with as few lines as possible, in a single source file, for testing whether or not the system can actually run the library, and less about how to actually use it.

We can also strive to improve those example as I'm definitively not happy with how they build, but it's not a trivial problem to solve with multi-platform into the equation, lots of devil in the details.

Glad to hear that. I understand it's tricky to stay generic and please everyone, but I find that it's a lot better to provide at least 1 way of doing things in full, whether that assumes glfw or what not, than to not provide any.

I would suggest we take a stand on the libraries used in the guide(s) and then stay consistent with those. Having examples also stay true to the those assumptions.

What do you think?

For actual function documentations, I would like them to be generated and that topic has some ideas about it.

Are you thinking along the lines of Doxygen? For many projects I think it makes the most sense, but can I propose an alternative? I think that since imgui is an open source project with lots of potential contributors, it might make more sense instead keeping documentation simple and making contributing to it as simple as possible.

You could use something like GitBook.

If you make it simple to fix mistakes and append both guides and reference material, I think the docs would be much more alive, complete and accurate than it could ever be if automatically built.

Here's an example of how I envision things.

• https://mottosso.gitbooks.io/cinder/content/

They can also be versioned and given a custom dns, along with statically built and hosted on GitHub Pages.

• http://api.pyblish.com/

There's definitively a lot to do there as ImGui will slowly head into becoming more of a community

I'd be happy to setup Discourse for you, hosting is $5/month on DigitalOcean. I think it could really spark collaboration and create a persistent knowledge base. It's also useful for what you might normally use a blog for; such as release notes or news.

[ocornut]

I'm looking for an example with as few lines as possible, in a single source file, for testing whether or not the system can actually run the library, and less about how to actually use it.

To me that's exactly that those examples/ are doing tho.

Glad to hear that. I understand it's tricky to stay generic and please everyone, but I find that it's a lot better to provide at least 1 way of doing things in full, whether that assumes glfw or what not, than to not provide any.
I would suggest we take a stand on the libraries used in the guide(s) and then stay consistent with those. Having examples also stay true to the those assumptions.
What do you think?

I absolutely don't understand those statements above, sorry. Can you try rewording the whole thing? What does "at least 1 way of doing things in full" stands for? "take a stand on the librairies used in the guide" ? I don't believe/think the guide would have much to do with the librairies. The vast majority of code we have to document apart from "Getting started" will be portable ImGui code. Maybe you can draft your vision of Getting Started if it helps communicating what you mean.

The example are here so people using different backends/engine can copy and paste the implementation code and have them ready to use.

Are you thinking along the lines of Doxygen?

I am thinking what is discussed in #435.
Have a separate project with lots of manually crafted tests and those tests can optionally emit output in the form of gif/screenshots + code + text, to be used in e.g. a wiki or another publishing platform. Ideally automate 100% of it, but realistically maybe still some manual intervention. So that framework would be both for testing and for creating documentation. That would be all raw C++ and it shouldn't impact on the actual ImGui code much (aka not spamming the code with Doxygen style comments).
That approach is because I was thinking mostly documenting with code examples (with screenshots) and less up with large walls of text. Code being the priority it is easier to have the code in.. source files.

Sorry for the hasty answer - I will have to look at your links in more details later but I am also overwhelmed by things to do so it may take a while until I form better answer. So don't hesitate to draft what you are thinking if you think it makes sense.

[mottosso]

Hi @ocornut,

I've produced an example of how I envision a getting started guide to look and feel, with some notes at the bottom for how it can be improved.

• https://github.com/ocornut/imgui/wiki/Getting-Started

Let me know what you think.

[ocornut]

Hmm.. I am really confused about this now.

I don't understand why the example stray away from opengl_example/ when it is basically the same-but-different. Part of the idea of those examples is also that the user can use the imgui_impl_ files WITHOUT having to look at them. So this guide is both showing you more than what you need to if you are using glfw (which is the intended audience), while also being incomplete (e.g. lacking keyboard, etc.).

From that angle, I am not sure I see the added value here. But I see the potential for a) luring people into wrong direction (only a fraction of choices available on wiki vs code, so they end up in a spot with much more limited choice and aren't directed to others) and b) encouraging people to reimplement something they don't have to, making further updates harder. If the target audience for a given article is locked to e.g. Linux/GLFW then shouldn't the instructions be cd opengl_example; make; ?

It feels like you are just recreating the existing example, as your todo are just leading there. For example when you say:

Remove need to manually upload texture to GPU in setup(), can/should be included in ImGui?

This is exactly what the imgui_impl_ files are for. Those non-standard platform things can't possibly be integrated in core because the library wants to function with thousands of other platforms, aka the platform that the user is using/making.

Additionally, if we refer to e..g GLFW we have to make it 5000% clear that it isn't a dependency of ImGui but rather part of the example of how to open a window and render triangles.

I am curious about your own experience getting started with ImGui with GLFW and if you had to reimplement this or if you couldn't just build/run the example and copy the imgui_impl_glfw.cpp file into your app. The comment at the top of opengl_example/main.c says:

// ImGui - standalone example application for Glfw + OpenGL 2, using fixed pipeline
// If you are new to ImGui, see examples/README.txt and documentation at the top of imgui.cpp.

The comments are the top of imgui_impl_glfw.cpp says:

// ImGui GLFW binding with OpenGL
// In this binding, ImTextureID is used to store an OpenGL 'GLuint' texture identifier. Read the FAQ about ImTextureID in imgui.cpp.

// You can copy and use unmodified imgui_impl_* files in your project. See main.cpp for an example of using this.
// If you use this binding you'll need to call 4 functions: ImGui_ImplXXXX_Init(), ImGui_ImplXXXX_NewFrame(), ImGui::Render() and ImGui_ImplXXXX_Shutdown().
// If you are new to ImGui, see examples/README.txt and documentation at the top of imgui.cpp.
// https://github.com/ocornut/imgui

Perhaps the main.cpp file should refer more explicitly to the imgui_impl files.

Mind you I still think Wiki is a great idea but I'd like to clear out the confusion above!

[mottosso]

Ok, no harm done. :)

Part of the idea of those examples is also that the user can use the imgui_impl_ files WITHOUT having to look at them.

Aha, I think we are getting somewhere. This was not obvious to me.

I think these.. shall we call them "reference implementations"?.. are great, but it wasn't clear to me that that's what they were. To me, an example is an example of how I can use imgui. In the example there are three source files, so I understood that I would need the contents of those files for any and all of my projects.

It seemed a bit much, and this was what sparked my interest in trying to build a smaller example.

A misunderstanding, to say the least!

while also being incomplete (e.g. lacking keyboard, etc.).

Yes, this I still believe is needed. This is what I meant by minimal. It doesn't have to do everything. It should only include the absolute bare essentials for getting anything on screen at all.

Think of it as the equivalent of a hello world example; pointless, but critical for newcomers such as myself.

This is exactly what the imgui_impl_ files are for. Those non-standard platform things can't possibly be integrated in core because the library wants to function with thousands of other platforms, aka the platform that the user is using/making.

Perhaps there is a better place for these reference implementations than being bundled together with the examples.

If they aren't meant to be written by the user, then I would expect them to be part of the library alongside everything else that isn't meant to be written by the user. But I can see what you are saying in that it would also bloat the currently generic code.

This isn't the place to discuss it, but perhaps a /platform or /reference directory from which the user may optionally #include these reference implementations?

#include "imgui/platform/glfw3.h"
/* Application code here */

If you are interested in this change, then I think we should pop open another thread about it to keep the topic clean.

I am curious about your own experience getting started with ImGui with GLFW and if you had to reimplement this or if you couldn't just build/run the example and copy the imgui_impl_glfw.cpp file into your app.

I glanced at the contents of each example and ran away in fear of not understanding what it was doing.

Without a hello world example, it was difficult for me to know whether the errors I was getting was due to something in the lengthy examples or somehow related to my environment.

Bottom line is, I never got those examples running and I didn't try very hard.

The comments are the top of imgui_impl_glfw.cpp says:

Maybe this is just me, but comments in source code is the last place I look when trying to understand a new software project. And frankly I haven't gotten frustrated enough to get there yet.

Perhaps the main.cpp file should refer more explicitly to the imgui_impl files.

I don't think so, I think what you need is a getting started guide.

[ocornut]

Perhaps there is a better place for these reference implementations than being bundled together with the examples.
If they aren't meant to be written by the user, then I would expect them to be part of the library alongside everything else that isn't meant to be written by the user.
This isn't the place to discuss it, but perhaps a /platform or /reference directory from which the user may optionally #include these reference implementations?

The thing is that it isn't a black and white situation. Advanced users are likely to want to adapt this code or borrow only part of that. E.g. lots of users are building their own engine over OpenGL may want to borrow the rendering function but rewrap the inputs their own way. I have found many subtle/minor cases where altering this code may be useful once you use it in a real project, and it is hard to handle every single case without bloating those examples.

If the issue is discoverability then we can update the docs/comments and a Getting Started wiki may help. Note that pretty much every single file says at the top something along those lines:

// See imgui.cpp file for documentation.
// Read 'Programmer guide' in imgui.cpp for notes on how to setup ImGui in your codebase.

While I appreciate and understand the curse that programmers don't read documentation that are offered to them (I often don't myself and go on ask authors only to find the answer in the docs I didn't read then feel ashamed...often because of multiplicity of doc sources makes it more confusing) , I don't think they will necessarily find a read a Wiki page either. That curse carries over many mediums. We have to keep hammering links and information to redirect the user to the right place from every piece of land including source and web. We have to make sure the information is correct, up to date and easy to digest. Lots of work has been put to that but more work is needed!

Regardless we will develop the Wiki so why not develop the Getting Started section and paving the way there.

I glanced at the contents of each example and ran away in fear of not understanding what it was doing.
Without a hello world example, it was difficult for me to know whether the errors I was getting was due to something in the lengthy examples or somehow related to my environment.

Those are the hello world examples. You'll find there's not many differences between opengl_example/ and what you have posted above. Yours is a little shorter but for that small amount of difference I'd rather have one single 100 line example that handle 99% cases rather than one 80 lines example that handle 80% and another 100 lines example that handle 99%. Don't you think?

I am very interested in your feedback and I think we can turn it into a concrete improvement. In my experience as a struggling new user you want to first take note of the struggle/issues you faced, because they are super important feedback. Then study/understand the whole thing a little better and then once you have that understanding get back at the issues you faced and see how you can fix/improve it now that you understand both side of it.

I don't think the existing example are bad but we can improve them.
Perhaps the wiki Getting Started should focus on:

• describe briefly the library architecture
• tell you how to compile an example
• tell you how to adapt it to your own project (may be simple copy, or a little more depending on engine)
  But not dwelve into too many minutia that are better served by the source?

Bottom line is, I never got those examples running and I didn't try very hard.

Didn't they compile? What was the problem? Those examples are meant to compile on your system. If they don't this is the number 1 issue to fix for me! :)

I don't think so, I think what you need is a getting started guide.

There is a "PROGRAMMER GUIDE - Getting Started" section but I should totally tweak that to show the word "Getting Started" in the top index.

Some of that content can be adapted and improved for the web, and depending on where we get it may make sense to delete some of the in-code comments.

[mottosso]

The thing is that it isn't a black and white situation. Advanced users are likely to want to adapt this code or borrow only part of that.

I think we are talking about the same thing here. This is exactly what I would expect from a reference implementation. To be an example of how you could do it. Use it, or don't use it. It's just a reference.

For getting started documentation, I think the first priority should be the oblivious new user; not the advanced one.

Those are the hello world examples.

Yes, I think you are right. Since I learnt that the majority of those examples were in fact reference implementations, the main.cpp is as short as I would expect a hello world example to be.

What I meant was that I glanced at each example as a whole, running away from the reference implementations, thinking they were part of what I had to know and understand to use imgui.

[mottosso]

Sorry, hit the button before I was finished.

There is a "PROGRAMMER GUIDE - Getting Started" section but I should totally tweak that to show the word "Getting Started" in the top index.

Ok, I'll just go ahead and say it.

I don't think documentation belongs in your source files. I think they scare away new users such as myself and that it makes improving and contributing to it incredibly frightening.

For example, there are numerous spelling and grammar errors in most of them that anyone could have fixed but won't.

The Wiki might not be the best place for it, but it is a lot better than in the source files.

Perhaps the wiki Getting Started should focus on:

I think that's an excellent list!

[ocornut]

For example, there are numerous spelling and grammar errors in most of them that anyone could have fixed but won't.

Please submit a PR! My English is part of the reason I would like the auto-generated documentation to focus on code+screenshot rather than blurbs of text.

[mottosso]

Please submit a PR!

Aw man, you're not hearing me. :)

[ocornut]

That's the immediate next step and it will take you 5 minutes, whereas wiki is a more profound step. Most of those code comments probably won't need to be removed.

[ratchetfreak]

one thing that I don't really see is what the render callback should do and what data it gets to do it.

Currently that needs to be divined from the demos which requires knowledge of the API that the demo in question uses.

[mottosso]

Thanks @ratchetfreak! Would it help with a few lines of documentation about what each function from the header file does, along with motivation for its existence and alternative ways of approaching it?

[ocornut]

Hi. Just wondered if your lost interest/motivation on this? (seeing the typos never got corrected :)

Any extra docs is great and fine but it needs to be done in a way where the docs are guaranteed up-to-date, ideally because it is automated. Many attempts at doing something are one-off-ok-bye, which is why I am cautious with people proposing to help before they actually use and rely on ImGui seriously. It's really better when you know you are going to like and use the library and fit in the ecosystem. It doesn't matter if a solution is arguably better if I can't pragmatically make it happen so I need to gauge ideas from the angle of how likely the prospect of it happening is.

I think the first priority should be the oblivious new user; not the advanced one.

FYI we think we already have an ok amount of documentation in line with the state of the library (unfinished) and the state of available support resources (little). Incremental improvements keep happening every week. But I said it a million times in other threads, I honestly think it would be detrimental to open the library to too many casual users before more of the missing features are added and stable. Containing growth keeps it more healthy and me more sane.

Anyway #435 is still one of my most-wanted. I have a project for serious dev+doc that I would like to pitch and work on from January onward.

[mottosso]

Hi, sorry for the delay.

In short, yes, I've lost some motivation and interest for now. As it stands, our goals are just too different.

Many attempts at doing something are one-off-ok-bye, which is why I am cautious with people proposing to help before they actually use and rely on ImGui seriously.

As an example, we differ here. I think the solution isn't finding a few to manage complex documentation long-term, but rather to find a method with which many can manage simple documentation short-term.

For example, the typos that I found. With what I have in mind, I could have spent 5 minutes fixing those bugs, without any prior knowledge of:

1. Your project or ecosystem
2. Doxygen, or any other automatic engine and syntax
3. GitHub, or know about forking and pull requests.

The same goes for fixing broken examples or adding pictures to code.

Add to that, if I didn't want to fully commit to making changes to the project, perhaps because I am not confident enough that my change is worth making, I could instead add a comment on individual paragraphs and start a discussion about whether a change is actually necessary.

Because of the lightness, the documentation would not only stay up to date, it would stay alive.

But again, IMO. I currently have no interest in setting up automated documentation. That might change, and if it does I'll get back to you.

[ocornut]

Well it is a balancing act. Of course editing a Wiki is easier than fixing typo in source code (which should also take 5 minutes and PR are proposals so also easy to discuss), but it also mean stretching us (me) thinner than we are now. ImGui works because it is so carefully cared for and tweaked in great details. Letting people who aren't actually using the library write the documentation nilly willy is also a risk at diluting the quality of information badly. We don't need to lock on a few to "manage" complex documentation, we need to make sure the documentation is worthy and create sustainably with the little resource this project has. The internet is full of people who barely understand C++ and are trying to use this library. I want us to do our best to make it easier for them, but I don't want them to write the official documentation.

We are aiming for the same things, except I am choosing a direction based on working on the project during the week-end (gauging my own stamina) and witnessing dozens of people using it daily. You are choosing a direction based on your own confusion at trying to use and embrace the project, which I think is a very very useful and constructive drive (because you are identifying real issues) but IHMO you need to clear out the confusion before turning that drive into action, which means actually using the library and taking small steps within the existing framework. If I see evidence that this project matters to you and you are using it then I'll be more ten times more receptive to you bootstrapping a better set of documentation for others.

It is frustrating but I think it is the saner route to expand slowly and properly.
It's just not easy to contribute to this project I agree, this is way things are for many projects. The automated test-suite is an attempt at making it easier for programmers to contribute to the project. And a by-product of it would be to provide better documentation for end-users/programmers.

The same goes for fixing broken example

Not sure how you would do that without learning about Github or the project or coding at all :)

Let me know if you want to close this. Btw I am treating this very seriously and not ditching your proposal, those discussions are helpful and feeding the plan.

[ocornut]

PS:

 |   examples/        | Some examples for various backends and windowing libraries
 |   extra_fonts/     | Optional assets*
 |   imconfig.h       | Template for mandatory configuration file**
 |   imgui.cpp        | 
 |   imgui.h          | 
 |   imgui_demo.cpp   | An example***
 |   imgui_draw.cpp   | A mandatory source file****
 |   imgui_internal.h | Internal details, without guarantee of backward compatibility
 |   stb_*            | External library
* That should really be contained in its own repository :)
** That should really be optional :)
*** That should really be located in in `examples/` :)
**** That should really be merged with `imgui.cpp` :)

This is a prime example where adding this to documentation is a little counter-productive due to being a newcomer to the project, when all those choices were made very very consciously.

* Accessibility and visibility are key and the best documentation. If that is spread apart people don't know what is possible.

** There is a define for that IMGUI_DISABLE_INCLUDE_IMCONFIG_H, but again accessibility and visibility are keys. It is important that the user sees and attempt to edit this file because e.g. the implicit conversion features is a key feature to proper integration. Also discourage building imgui as a .lib which often result in the same thing, aka lack of user configuration that, aka missing on benefits. Unfortunately the system isn't ideal for people trying to use master git repository instead of copying the files, but we don't have a better solution now.

*** Again key to accessibility and visibility. This is the interactive documentation. It can't be moved away from sight. And there's no way it can be replaced by a wiki because it is an interactive piece of program. It should be always available to a maximum number of people even after they have integrated ImGui in their engine. Ideally any in-house tools should have the option of showing this at any time. This is a dead-strippable integral part of the library. People are already trying hard enough to remove it out of blind habit (in spite of all suggestions not to), moving it out sight in the mess of the examples/ would be dramatic. It is to the benefit of the user/developer to have this available.

**** It was already debated to split imgui into more files as the old one .cpp version was too unwieldy, so it is now 3 cpp.

It is the responsibility of the library to guide the user to the best way they can use it through subtle or not subtle hints.

[mottosso]

Of course editing a Wiki is easier

For clarity, I am not suggesting we use the wiki. The wiki allows anyone to make edits without informing anyone, which makes it very difficult to manage quality.

I'm suggesting GitBook, which has version control and support for hosting multiple versions (e.g. one per major version of the framework) and support for comments, issues, synchronisation with a GitHub account and custom CSS styling to name a few. You could automatically push portions of it via webhooks and something like Travis CI if you wanted a best of both world.