Closed tajmone closed 2 years ago
AnssiR66
commented
3 years ago Hi Tristano, I have been on a long hiatus with the whole project, sorry about that. If you are still keen on doing something about this, it is ok, and you have my permission do edit the examples and contents, otherwise I can do the changes.
tajmone
commented
3 years ago Thanks Anssi! I've too been caught up with all the life changes of the recent tribulations, and haven't managed to do much on the Alan side. But I'd like to carry on the work at some point in the nearby future, so thanks for the permission.
There are still some library related bugs which need to be addressed (all of them covered in Issues); some of them affect the underlying structure of predefined library objects, so fixing them might require some deep thinking and checking for unexpected consequences.
Overall, the Beta work for the next StdLib version is fairly good — we have new features that work well, and the bugs which have prevented a new release were already there before (many small bugs were actually fixed). So we should consider whether to create a new updated StdLib release even if these bugs are still there (since they are also present in the latest release).
Maybe the documentation is something that needs to be polished before a new release, whereas the bugs can be postponed to a future update.
AnssiR66
commented
3 years ago Yes, I agree that the documentation can be brought up to date, and then the latest version of the library is usable and could be distributed to the user base. The bugs, as they are not crucial, can be dealt with at a later date. Besides the clothing class, what exactly are the other themes in the documentation that need updating? I will also have a look.
From: Tristano Ajmone notifications@github.com Sent: Sunday, August 30, 2020 12:26 AM To: AnssiR66/AlanStdLib AlanStdLib@noreply.github.com Cc: AnssiR66 anssir66@hotmail.com; Mention mention@noreply.github.com Subject: Re: [AnssiR66/AlanStdLib] StdLib Manual: Updating Examples & Contents (#76)
Thanks Anssi! I've too been caught up with all the life changes of the recent tribulations, and haven't managed to do much on the Alan side. But I'd like to carry on the work at some point in the nearby future, so thanks for the permission.
There are still some library related bugs which need to be addressed (all of them covered in Issues); some of them affect the underlying structure of predefined library objects, so fixing them might require some deep thinking and checking for unexpected consequences.
Overall, the Beta work for the next StdLib version is fairly good — we have new features that work well, and the bugs which have prevented a new release were already there before (many small bugs were actually fixed). So we should consider whether to create a new updated StdLib release even if these bugs are still there (since they are also present in the latest release).
Maybe the documentation is something that needs to be polished before a new release, whereas the bugs can be postponed to a future update.
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/AnssiR66/AlanStdLib/issues/76#issuecomment-683343772, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ABO2KHSLXYVGNMS2U7UDYJTSDFXBTANCNFSM4HQ5X73Q.
tajmone
commented
3 years ago Besides the clothing class, what exactly are the other themes in the documentation that need updating?
I can't remember right now but I have kept some notes locally somewhere, plus we have all the Issues and commits that track the history. Mostly is about changing the examples in the StdLib Manual which require some adaptations due to various enhancements that were done along the line — some of them concerning the current 2.1 version, because the documentation was lagging behind.
I don't think it's going to be a huge deal. The bigger work is porting the original document from PDF/Word to AsciiDoc, which I already started working on. Now that I have your permission to edit it, I can restructure it according to AsciiDoc books format, and once that is done all future updates will be much easier.
I only need a few weeks to settle in the post-holidays changes to the daily life rhythm, and then I'll manage to cut out and allocate some free time for the project and get back into work mindset. It will take a few days to catch up from where we left, but thanks to the tons of notes it will be easy to take on where we left.
Reasonably, we can expect the new version to be release somewhere around mid November, all nice and polished, so that Alan users could take advantage of the Christmas holidays to dive into it,
tajmone
commented
3 years ago OK, I'm starting to catch up with where we left. So, the StdLib Manual is already being worked on, in a dev branch:
https://github.com/AnssiR66/AlanStdLib/tree/dev-2.2.0-docs/extras_src/manual
The new document is in AsciiDoc and uses snippets from real Alan sources in its examples. The generated HTML doc is in this other folder:
https://github.com/AnssiR66/AlanStdLib/tree/dev-2.2.0-docs/extras/manual
And here is a Live HTML Preview:
This system (if I remember correctly) not only helps to automatically update all code snippets and game-play output in the Manual (in case the source were changed, or the library produces different output), but it also allow to check that the examples are working as expected.
This should definitely be an improvement because now the documentation is going to be interwoven with the actual StdLib sources, and any changes will be automatically propagated.
The only reason I didn't finish the AsciiDoc adaptation was because I was waiting for your permission to carry out the required editing. So, now it should be fairly straightforward to finish the work. I'll try to stick to the original Manual as much as possible. As for improvements to the contents, we could think of those after the v2.2. update, with more calm and less changes at stake (there's quite a number of changes to handle already, with the shift to GitHub and AsciiDoc).
AnssiR66
commented
3 years ago All this sounds good and we can do as you suggest. I appreciate your input as I don't have the expertise to make the conversions to AsciiDoc. Let me know when you need help!
From: Tristano Ajmone notifications@github.com Sent: Monday, August 31, 2020 9:37 PM To: AnssiR66/AlanStdLib AlanStdLib@noreply.github.com Cc: AnssiR66 anssir66@hotmail.com; Mention mention@noreply.github.com Subject: Re: [AnssiR66/AlanStdLib] StdLib Manual: Updating Examples & Contents (#76)
StdLib Manual Dev Branch
OK, I'm starting to catch up with where we left. So, the StdLib Manual is already being worked on, in a dev branch:
https://github.com/AnssiR66/AlanStdLib/tree/dev-2.2.0-docs/extras_src/manual
The new document is in AsciiDoc and uses snippets from real Alan sources in its examples. The generated HTML doc is in this other folder:
https://github.com/AnssiR66/AlanStdLib/tree/dev-2.2.0-docs/extras/manual
And here is a Live HTML Preview:
This system (if I remember correctly) not only helps to automatically update all code snippets and game-play output in the Manual (in case the source were changed, or the library produces different output), but it also allow to check that the examples are working as expected.
This should definitely be an improvement because now the documentation is going to be interwoven with the actual StdLib sources, and any changes will be automatically propagated.
The only reason I didn't finish the AsciiDoc adaptation was because I was waiting for your permission to carry out the required editing. So, now it should be fairly straightforward to finish the work. I'll try to stick to the original Manual as much as possible. As for improvements to the contents, we could think of those after the v2.2. update, with more calm and less changes at stake (there's quite a number of changes to handle already, with the shift to GitHub and AsciiDoc).
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/AnssiR66/AlanStdLib/issues/76#issuecomment-683956020, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ABO2KHXN25WL55ZJWSA6NI3SDPUXJANCNFSM4HQ5X73Q.
tajmone
commented
3 years ago @AnssiR66,
I've started working again on the StdLib Manual, and have already updated its version to v2.2-WIP in view of the upcoming release. You can always track the update via the Live HTML link pointing to dev-docs:
I'm taking some editorial freedom in adapting the current text to best fit the AsciiDoc editorial style:
Of course, anything you don't like can be easily reverted to its original, but if we want to come out with a full release by mid-November, with documentation and all, I really have to rush on this and make the most of each working session — i.e. edit and fix as much as I can while reading through, to save time.
I still don't have an exact idea of when the first polished draft will be ready, but I hope that in a couple of weeks time (after having read through the whole Manual again) I should have a good estimation of its ETA.
As I'm taking on from where we left, many ideas are coming to mind on how to optimize the whole toolchain in the future — and once the next release is over, and all dev branches are merged, I'll spend some time cleaning up, polishing and optimizing all the scripts and the repository structure, to make future development and maintainance better and easier.
As a last note, I think that many section titles are really too long and should be shortened (i.e. too long for English standards, where verbosity is not considered a virtue). For example. the section What to read if you’re familiar with ALAN but haven’t used the standard library v1.0 is way to long (especially when cross-referenced, for it will be shown in full in the text).
That title could be cut down to something shorter, like If you’re familiar with ALAN but not the StdLib — which version (1.x or 2.x) is irrelevant in that section, and the "what to read" part is not necessary, since it's part of the Introduction, so stating the target audience should be enough.
Ok, that's just an example, and probably we could come up with something better than the solution I sketched above, but I hope you odn't mind me trimming down the verbosity of long sections titles — and if you don't like them, it's easy to change them again without affecting cross references.
EDIT:
Actually, the following sections:
could be re-titled to:
which, IMO, is fairly intuitive for the reader — he/seh'll know that each of these Intro subsections cover newbieness in growing order. Short titles like these are more manageable, both for readers sifting through the TOC, as well as for cross reference texts and anchor ID (i.e. #alan-newbies, stdlib-newbies and stdlib2-newbies).
Are you OK with similar changes? I know it's quite a radical change in style, but from experience working in book publishing, people want manuals and ref-docs to be easy to navigate and lookup, so the general rule is less is more.
Ciao @AnssiR66,
As I'm reading through the StdLib Manual text and its various examples I see many sections and examples which need to be updated to reflect latest library changes (e.g. clothing, bu also a few other small features that were added).
So, I was thinking of creating a milestone for examples/contents updates, so we can keep track of what needs to be changed/fixed and what was done already.
My question is wether it's OK with you that I just go ahead and edit these as I go along in the text — i.e. how much freedom I have in terms of contents changes?
Obviously, for big decisions (like dropping the
brief/verboseverbs) I won't change anything without asking you, but for those contexts where I'm aware of the library recent updates, I could just go ahead and edit them according to the original intention but in line with the current library status.Because changing contents is a delicate issue, I'll wait for your reply on this.