Documentation? about guilite HOT 14 CLOSED

I would like to add my 2 cents.

I think a good documentation is synonym to allowed more adoption of a technology.

It's OK not have enough time to do something better for your interested users, but you can't think too that everyone could have time to debug a project to learn or worst think that your interested users are 'weak' for don't do it.

Even if they don't have knowledge enough, the documentation it's for help them, even an advanced user could be helped.

I think great if we have more friendly documentation centered to the beginner user perspective, with levels of beginner, intermediate and advanced tutorials for example.

Everyone who joys programming, definitely will be thankful, would be great, but if not possible at moment, it's OK too.

As open-source project, I hope the community can collaborate one day at this subject

Sorry for reopen the thread.

Regards for all.

from guilite.

@RecursiveDescent
Did you bother to read this:
https://github.com/idea4good/GuiLite#easy-to-learn-and-support

• How to use GuiLite?
• Design specification
• How to Layout widgets?
• How to build unicode font/bitmap resource?
• How to switch theme?
• How to dispatch messages?
• UML chart of GuiLite core

from guilite.

what I understand, your coding skills are weak.
so you wanted a example which will build without errors instantly ?

install Visual studio 2017 with Desktop development with C++ .
and open any *.sln file

from guilite.

what I understand, your coding skills are weak.
so you wanted a example which will build without errors instantly ?

install Visual studio 2017 with Desktop development with C++ .
and open any *.sln file

So, a javascript interpreter and operating systems development is weak? No, I simply did not have the time to sit there reading the code to figure it out, as many people do not feel like doing.
I tried hard not to make this reply but I don't see what place what I understand, your coding skills are weak. has in a comment.

from guilite.

@RecursiveDescent
If you are js developer, then I know C/C++ is toughest for you.
Actually, C requires highest programming skills.
Whereas js doesn't develop much concepts like double,float,int32/64 ... etc.
Even a declaring string is hard in C. Whereas js is too easy that good no. of developers are either js or py.

What are your assumption about GUI ? so that I can suggest better.

from guilite.

It's more friendly to users by providing APIs and detail func infos.

from guilite.

@graysuit documenting the complete API calls is part of a good documentation, and this project has none of this. Sure, it's not mandatory, but you can't expect developers to dive into the source code to find out which functions are available, what they do, the requested parameters, etc.
And noone asked anybody to teach them programming, he just politely asked for some documentation.

from guilite.

what I understand, your coding skills are weak. so you wanted a example which will build without errors instantly ?

install Visual studio 2017 with Desktop development with C++ . and open any *.sln file

Dearest Gray Suit,
It does NOT matter about this programmers skill. they speak for mass adoption, they speak for being user-friendly, and you cannot be rationally opposed to this and so dismissive of documentation.

Do you consider documentation to be for weak amateurs!? It is actually the hallmark of professionalism.
Competent domain authorities can explain domain concepts to outsiders in a clear and simple fashion.
This person was suggesting something not merely to alleviate their personal laziness, but to make this library accessible to
people who are not telepathic and make it look nice when someone or some company is choosing a GUI library.
Documentation is an ASSET.

Documentation on most projects on Github need improvement.

• API documentation should CERTAINLY be fleshed-out separately from source code examples.
• "Getting Started" needs to be explained in detail:
  "GuiLite is a header-only library, so it should be straightforward to integrate into your application."
  with an #include .cpp example but never ONE TIME mentioning why src/ and all the various projects, the static library.a, and even header-only.sh exist and how to USE GuiLite in these various formats. One section or document per format.

I realize that this issue is closed, but I see this response and attitude demonstrated above as very shockingly counter-productive.

from guilite.

@vectorselector I respect your opinion. Not sure why I look so harsh.

But you didn't read context. I replied to:
I was looking for something fast and that would work, so I didn't really have the time to be reading through the source to find the right functions to use.
and Fast food isn't digested. So simply I advised him to first learn VS with C++. Without it, even documentation can't help.

And about documentation, I know open source/free product will not grab your finger and make you visit all city. Traditionally, C/C++ developers need to figure out by themselves by unit testings and reading internal core. And even it have tons of samples, FAQ...
Its new mindset of new non object oriented language programmers. Not C or C++.

1. I agree. API usage documentation needed for guilite.h. Something a webpage like libvlc as example.
2. Its not responsibility of guilite to explain what static libraries, *.sh *.bat scripts, headers do. Offcourse .sh/.bat scripts used for building via command line. Headers helps compiler in error raising. Headers just contain headings. The working code is inside libraries. (Atleast general cpp,headers,libraries,scripts knowledge is required by guilite)

and again. Don't think this rude or aggressive.
This is my opinion, you may disagree or I may disagree with you.
Hope you understand. Thanks

from guilite.

By fast and would work, at the time I was referring to something easy to get working and simple to setup because I was working in an environment that I couldn't get something as fat as qt to work in, but for the advanced project I was going to use it for just some basic layout wasn't going to do it, and it was faster to just force qt to work than to wade through the header file(or tons of examples in separate repos) making my own map of everything as qt provides good enough documentation.

API usage documentation was exactly what I wanted, and for a project with 5.8k stars there was really no reason to still not have it.

and Fast food isn't digested. So simply I advised him to first learn VS with C++. Without it, even documentation can't help.

Also, autocompletion is not comparable with actual documentation... But that's also another reason why I needed documentation since I was working where I didn't have it in the first place even if I had the knowledge to intuition my way around the autocomplete suggested functions.
After I got qt working I opened their documentation and that was it.

from guilite.

@vectorselector I respect your opinion. Not sure why I look so harsh.

But you didn't read context. I replied to: I was looking for something fast and that would work, so I didn't really have the time to be reading through the source to find the right functions to use. and Fast food isn't digested. So simply I advised him to first learn VS with C++. Without it, even documentation can't help.

And about documentation, I know open source/free product will not grab your finger and make you visit all city. Traditionally, C/C++ developers need to figure out by themselves by unit testings and reading internal core. And even it have tons of samples, FAQ... Its new mindset of new non object oriented language programmers. Not C or C++.

1. I agree. API usage documentation needed for guilite.h. Something a webpage like libvlc as example.
2. Its not responsibility of guilite to explain what static libraries, *.sh *.bat scripts, headers do. Offcourse .sh/.bat scripts used for building via command line. Headers helps compiler in error raising. Headers just contain headings. The working code is inside libraries. (Atleast general cpp,headers,libraries,scripts knowledge is required by guilite)

and again. Don't think this rude or aggressive. This is my opinion, you may disagree or I may disagree with you. Hope you understand. Thanks

I agree with your 2 points.
I don't think you were being rude or aggressive, just dismissive, and I simply wanted to point out that documentation is considered good in the circles I run in. I totally understand if a personal project is indecipherable to outsiders but is provided "as-is" in the form of github archival, in the hopes that it's useful to others etc. I would say that a GUI library hoping for further adoption meets the criteria: "needs good documentation"

There's also the issue of a language or build-tool newbie not being a newbie programmer, but perhaps coming from other circles: It also doesn't cost much to add selective informative tips for newbies: Example:

To build, use the usual cmake convention:

1. mkdir build
2. cd build
3. cmake ..

How shall new users of cmake realize the conventions when the documentation emphasizes the total feature set of cmake rather than how most developers use it? We are culture-bearers as well. We are ambassadors of culture.

I realize that teaching what a shell is will be out of scope for documentation, but all necessary steps to build and arrive at hello-world or somesuch is what I consider the minimum acceptable documentation. If the API is really only defined in a single header file and is minimal as such, place comments and extract them for at least a minimal API document with function type signatures etc.

from guilite.

I'm 14 days late but I meant like actual documentation on functions, their signatures, what they do etc. What's in the readme just throws a bunch of examples at you and assumes it shows you what the functions do.
I was looking for something fast and that would work, so I didn't really have the time to be reading through the source to find the right functions to use.

from guilite.

right,
and GUI-lite can't teach them programming.
That's what author of this issue is looking for. lol

from guilite.

I just say politely it looks well documented to me due to:

• good no. of examples for multiple platforms (qt,win32,mfc ...): https://github.com/idea4good/GuiLiteSamples
• contain build instructions
• just 4000 lines
• #49 (comment)
• ....

Documentation also address which function do what and what parameters we should pass...
https://github.com/idea4good/GuiLite/blob/master/documents/HowLayoutWork.md

But still I think I'm human and can be wrong as well.

from guilite.