-
Notifications
You must be signed in to change notification settings - Fork 9
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Defining roadmap to a feature complete web documentation #206
Comments
About SPA, I really feel static pages are better, they get better indexed on Google and other search engines, and they usually work with any browser. The fact SPAs work offline is nice - I have not seen evidence people actually install them though. About the chm, if we want to replace it, the new build possibly won't be that different html wise, as it would need to function in a limited html capacity - we probably don't want to throw a huge browser along with the AGS Editor to run the docs, and there isn't a huge offer of HTML reading C# projects or embeddable Web Views. It would be more about getting a good indexing system and then making the ui in C#. (On the topic of index, I have built some offline tools on this in the past, but using R, which has some really cool libraries on the topic, they can go through GBs of text do may be overkill for us. Shopping around I found an interesting indexing system using C#, lucenenet)
Lastly, about the Sidebar, I think we need to manually maintain it, with only a script to check there's exactly one link for every document, reporting missing and duplicates. There's anything that differentiates a "see also" link from any other link currently, so there's no way to grasp a tree structure from just looking into the files. |
But you're using an app, so any web improvement is probably useless for you! 😛 About SPA/CHM We can have both static and spa (not the installable kind), it's just that if we use the file:// protocol we must only use only one page,or the localstorage will be different for evey single document. Issue that would be solved with a micro-webserver like php or python's, or anything else that can serve files through the http protocol, if we want to keep it offline. Running from the http: protocol also has the advantage that I can async load other pages content via ajax and pretend the url has changed without actually leaving the page. Without http I can still use the # to fake page navigation, but I won't be able to make ajax calls, which sadly means I need a javascript way to have the contents. |
In my mind there are two separate parts to the manual:
Something like a printed manual or public website would likely incorporate both of those parts, and that is also where the indexing becomes more complicated. The script API is potentially much easier to index if it acts purely as a lookup of a symbol, potentially just an index entry that points to the function signature and a brief description of what it does (perhaps with a short example). Technically, if required, this could also be synced to docstrings in the source code to make sure that everything is actually documented and stays in sync with branches. The other part of the manual is more like a book, so that needs something that reads in a more structure way, but equally someone may be interested in how to do X, where the ideas, concepts, and examples surrounding X need to be somehow located, probably across multiple pages. I don't think anyone is using the CHM viewer because that is their preferred way to read the tutorial, more likely they would prefer that in a browser or exported as a PDF. I think what it provides is the fast API index lookup from the current script editor and the special focus rules for its window (which allows it to co-exist more nicely with windows of the application which invoked it). To replace the CHM viewer I think whatever replaces it should target editor support, and I'm suggesting any editor, not the Editor. It probably isn't a good idea to get hung up on the tooling before we know what the goal is. To suggest some ideas, how about trying to create the following two components:
Potentially there is substantial cross-over in how both of these are built and function, I imagine there would be multiple options for bundling the equivalent of the website with editor tooling and searching it, but does the above sound feasible as a way to replace the CHM viewer and have a better web-based manual (potentially resolving all three of the related issues linked in this ticket)? |
We should define actionable tasks for reaching the point where we can say the web documentation is good and complete.
And for that there are a few decisions to make:
It's fine even having a javascript array of topic-titles somewhere, that I can parse to build it.
It would also be helpful if I have access of it as an array, so I can match things like
Character.Say
exactly and offer it as a search result that positions the user at the correct anchor.I can find ways to make it fully work locally as a SPA without a webserver, but that will require having all the contents embedded either in the HTML or a javascript. Or, we could ship one of those third party micro webservers and serve it on localhost:somenumber.
It's also possible to render markdown on the fly straight from javascript, or even build search indexes locally and saving them on localstorage and then checking against build number to regenerate them.
I'd say only 1&2 should be considered for the short term. I would like to at least have the genindex content on a javascript array, so I can load the page with the correct anchor.
Related issues:
The text was updated successfully, but these errors were encountered: