Conceptually, a company which cares about a version of J should obtain a snapshot of the documentation for that version.
In my experience, many companies are not organized to do that. Often, the people making the decisions are short term thinkers who expect to delegate problem solving to specialists who already know what to do. This leads to the current corporate landscape. In other words, to some degree, you have a valid point. Though it feels like it should not be valid. That said, the release notes do document version-specific issues. But finding people who are willing to dredge through the information in that format can be difficult. A related issue is the divide between serving information to a large number of people, and the interactive development process as applied to serving that information. In the context of the wiki, we have software that is freely available to us, but which is written in a "foreign language" (php), and people who deal with that language usefully are few and far between. Especially people willing to do that work for us for free. We literally don't have anyone who can spin up a copy of the wiki and experiment with it on their local machine. There's docker images of the underlying wiki implementation, but when I've tried to spin one up I've crashed and burned. Nor do we have anyone inclined to build an adequate replacement for the wiki, let alone a team for any of that. (Much bigger project, also. And one which requires dealing with sequential issues. Something which I guess Henry's efforts are making more approachable, but.. still a mammoth project. Perhaps a wooly mammoth project.) There's a lot that could be done if we had ways of tagging information on a page by rank, by primitive type, by release version, with selectors so that a person could reduce the page to just that content. But that would also get into motivating people to build pages to that standard. So all of this would require highly motivated solo operators, along with a keen sense of vision, and a ruthless approach towards tossing disorganized content into "prepare for the future" bins (talk pages, maybe). So for now that kind of approach for the wiki is something of a fantasy. (Though, perhaps something someone could sink their teeth into as an interactive J book?) Anyways we currently don't have that and in the context of the wiki we won't have that, so I guess we need an organized plan / template which serves a similar end. Meanwhile... people have come to rely on nuvoc. And... the dictionary is historical rather than current. So I guess I'm proposing something that would be new. It might eventually replace nuvoc, but it would need a format, a plan and a name. We've been playing with collapsing regions, and sortable tables, and colors and categories, so those are tools we know we can bring to bear, especially if we can simplify / adequately document the processes of deploying them. Collapsing sections lets us handle one dimension. Tables let us handle two dimensions if the information is compact. Rank, type and version, along with references and examples seem like approximately 3.14159 dimensions. So... not a perfect fit, but... almost approachable? We've also seen, I think, that mixing reference work with tutorial work is problematic. There will be people who overlook both and then demand we cater to them - this is a large part of our potential audience. And, maybe we can entice them in some way? Anyways... I guess one starting point would be a page format for the reference work which we want nuvoc (nunuvoc? voc0? jvoc? jthesarus? jlooneytunes? ...) to be. This, with two or three example pages might help us more clearly see what we need to be doing to get where we want to be. A related (dependent) task would be documenting the procedures for building pages to this standard. But we can't get there without some experimentation, and that experimentation needs fairly clear goals, which lay out what we're looking for. (And I think what we're looking for is something similar in character to the j dictionary and/or a paper dictionary, but with the content of nuvoc, the release notes and even some of the labs. Much easier to fantasize about than build...) Sky high goals here. Needs barnstormers, I guess. Thanks, -- Raul On Mon, Nov 13, 2023 at 4:17 AM Jan-Pieter Jacobs <janpieter.jac...@gmail.com> wrote: > > As to point 2), this is indeed something I have wondered about: Nuvoc is a > great reference, but are changes by random people consistently checked for > correctness (even if, one might assume, they are made in good faith)? > On a related note, knowing for which version of J some explanation in NuVoc > holds is near impossible: J changed a lot recently, and Nuvoc relates to > the last version (or even the last beta version?), but I wouldn't know how > to find back documentation for an older version. This might be of concern > for companies who want to stick with a certain version, yet have the > documentation for supporting maintainable software. > > Just my two cents > Jan-Pieter > > > On Mon, 13 Nov 2023, 07:09 'robert therriault' via Programming, < > programm...@jsoftware.com> wrote: > > > == Report of Meeting 2023-11-02 == > > > > Present: Ed Gottsman, Raul Miller, and Bob Therriault > > > > Full transcripts of this meeting are now available on the its wiki page. > > https://code.jsoftware.com/wiki/Wiki/Report_of_Meeting_2023-11-02 > > > > 1) Ed plans to record a screencast of the demo and send the files to Bob > > so he can edit and post it up on Youtube. Ed feels the GitHub search tool > > will be useful for intermediate users because it provides some options in > > ways to use the code. Bob thinks that the important thing is that the code > > that is found is actually being used and not just the way that J coding is > > prescribed. This may be a very good way to onboard a J programmer to common > > coding practices. The GitHub search might also be a way to see changes that > > had taken place as new primitives are introduced. Ed plans to introduce the > > GitHub tool at the next meeting of the British APL Association meeting. > > > > 2) Raul raised the point that there is a difference between the Dictionary > > and NuVoc and that not all the information in the Dictionary has made its > > way across to Nuvoc. Bob wondered whether NuVoc might be administrator only > > edited to maintain the veracity of the source. Then there was a discussion > > on labs and the ways that these might be incorporated into use for the wiki > > and NuVoc. J Playground could accomplish this by loading labs into the edit > > window and then could be accessed from the terminal line by line. > > > > 3) Bob asked about the way that breadcrumbs were used in the wiki. In the > > new category tree, Bob has removed the breadcrumbs because they are > > redundant. If a link on the category page takes you to a new page that is > > not a category page then it might have a breadcrumb. Ed pointed out that > > there is a back arrow on the browser that will always take you back. Ed > > pointed out that two steps away would still be disconnected. Bob said that > > the sidebar would still have the main categories and there would be access > > to the map of the site on every page under the search bar. > > > > 4) Bob thinks that the J wiki search tool is working very well and feels > > that it works well with the categorization. Ed felt that it is really > > important to use the categorization because that is accessible for anyone > > with a browser. The J wiki search is only available through JQt. Ed points > > out that curation makes the ball of information in the wiki more > > accessible, but what he has done is more about presentation and the J wiki > > browser is the thing that accentuates the curation through good > > presentation. > > > > For access to previous meeting reports > > https://code.jsoftware.com/wiki/Wiki_Development > > > > If you would like to participate in the development of the J wiki please > > contact us on the general forum and we will get you an invitation to the > > next J wiki meeting held on Thursdays at 23:00 (UTC) Next meeting is > > November 16, 2023. > > ---------------------------------------------------------------------- > > For information about J forums see http://www.jsoftware.com/forums.htm > > > ---------------------------------------------------------------------- > For information about J forums see http://www.jsoftware.com/forums.htm ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
