monte at appisle.net
Tue Aug 1 20:02:38 EDT 2017
Thanks for your thoughts Andre
> On 2 Aug 2017, at 8:48 am, Andre Garzia <andre at andregarzia.com> wrote:
> Yes, I can give more details, I am not talking about library documentation as it is generated by lcdoc but the overall state of the documentation. The main issue for me is a UX one. The built-in LC dictionary UI is not good. For example, on my Surface 4 Pro, I can't change the little dropdown to select the httpd API as the popup list is larger than my screen and does not scroll with the trackpad.
Yes, we know this is not right. Plans are afoot to merge all the extension APIs into the LiveCode script one which will solve the problem above.
> That is just an example, a simple list of opportunities for enhancement would be:
> * Provide sample stacks for all LC dictionary entries (multiple entries can share the same sample but no entry can be without at least one sample). The sample stacks need to be something that the person can click and run.
Yes we need some kind of related resources thing where we can setup two way links between in a lesson, example stack or interactive tutorial.
I’ve opened a report here http://quality.livecode.com/show_bug.cgi?id=20215 <http://quality.livecode.com/show_bug.cgi?id=20215>
My suggestion is the tags be expanded to all resources rather than just api so it’s easy to setup a blob of resources about a thing.
> * A better wiki or comment system.
We are encouraging people that have something to contribute to do so directly to the document as that way it both gets reviewed and more visibility. I know this presents a bit of a hurdle for some potential contributors but it also means there isn’t yet another place for good information to get lost in.
> * Libraries need to be more discoverable.
Indeed (mentioned above)
> Right now we have documentation spread all over the place. There are things in release notes, things in emails, stuff in the dictionary, stuff only on the website, and finding things is quite hard. The navigation is challenging, for example, searching httpd on the website yields nothing. I had to go to github and look for the source.
In the past it was possible for stuff to be in the release notes but not documented in the dictionary but that shouldn’t be the case with anything new and anything that is not in the API please open a report on.
We know we need to do better with the docs, however, there are a *lot* of them so community contributions really do need to be a big part of getting them right. Adding tags is a good place to start.
More information about the Use-livecode