| * | Dev Documentation Visibility | All | - Ideas for the type of developer-facing documentation we think would be most helpful for new developers
- How we might bring existing documentation up to date and ensure it's consistent
- etc.
- Jeremy Huff: This is timely with developer advocate starting next week. PD includes developer documentation. Knowing what we are missing or could be improved, would help to direct advocate.
- Jeremy Huff: As PO for a new application, onboarding developers at TAMU, hear a lot of heartache about out-of-date docs. Or not finding what they need to assess a particular thing. What types of docs would be helpful? Compiling a list of what his team wanted.
- Maccabee Levine: Setting up a new env. many wrinkles / variations.
- Marc Johnson: What do we mean by new dev environment?
- Maccabee Levine: Differences in FE and BE work definitely.
- Jeremy Huff: Found it is easier to rely on a pre-deployed module in the cloud somewhere, running the BE off of his dev machine. Scratch environments help.
- Marc Johnson: Single-server setup doc isn't intended for development, but for operations folks to try out FOLIO. Vagrant was essentially deprecated years ago, not sustainable to run full FOLIO on a PC. Scratch environments are not official FOLIO, gracious from vendors, ask Kitfox. Short term, can invest in tweaking existing documentation – very little stopping folks from that. Longer term, how does the community want to support this stuff. As a developer I never ran a full stack on local machine.
- Maccabee Levine: I actually do run full FOLIO as a Vagrant box on my local machine. Dev advocate is an attempt to address the concern of method to get the docs up to date.
- Zak Burke: Three places to put docs right now. 1) stuff within a repo. 2) wiki. 3) dev.folio.org. Where to put stuff is a struggle. Also two types of docs, 1) component-level how does this module work, makes sense to locate with the code in the repo. But you also need the 2) higher-level guide documentation. Struggle with that kind the most, it falls out of date and we don't have good patterns. Slack is not easily bookmarkable, hard to find again. As a dev, how to get some of that guide-level documentation maintaned, and drive people towards it. Would love to see dev docs moved to either the wiki or dev.folio.org and retire the other. An unmaintained library becomes a dumping ground; need curation to be part of someone's job (i.e. dev advocate).
- Marc Johnson Agree that consolidation is needed. Someone needs to make that call, and ideally before the advocate is actually writing documentation, if it's the place we don't prefer. Not a massive piece of work to migrate, but can't just move and it works.
- Jeremy Huff Do we have a preference on where to consolidate? Agree with Zak's analysis. Process/guide-level documentation is what's in question; wiki vs dev site.
- Marc Johnson If it were me, prefer wiki, because FOLIO puts most things on the wiki. Except official documentation as its own separate thing (docs.folio.org). Another case to move away from dev.folio.org is that the folks who originally set it up no longer have the capacity to contribute. Councils and dev teams seem to have chosen the wiki. We are a community with lots of people with information architecture expertise, and we really struggle with information architecture.
- Jeremy Huff There are aspects of dev.folio.org I would miss, like API doc lists. But walkthrough / guides feels better on the wiki. Community authorship also a question, dev site doesn't look as open to changes, wiki is more obvious how to contribute.
- Zak Burke Agree API reference page should not go away, but is there a way it could be part of the wiki and updated there.
- Zak Burke Would like consistent API documentation across modules, not view-1 through view-1. Spring Base documentation is not on endpoints, it's on function names, so documentation is really hard to navigate. For a REST API, all you have is a path.
- Craig McNally Paths are there also, it's an artifact of how the docs were generated.
- Zak Burke But you can't search for it; have to know the method name first. Can't search by path. Would love consistent documentation. Doesn't matter if it's RAML or Spring or whatever else.
- Jeremy Huff Agree, and method names are in reverse order of the path.
- Marc Johnson We're at the behest of third-party tools we use, and we have a variety of them, with no plan to get stuff off the old way of doing it. So that split won't go away until we get off RAML / RMB and Vertex, or we use or build tools to build the docs.
- Craig McNally Agree that consistency in API documentation would be nice. Larger problem is that it is incomplete. Some modules don't even appear on the list. I.e. Groovy-based modules, mod-licenses, mod-agreements, mod-serials-management.
- Marc Johnson They do end up in the list, but driven by a different way.
- Craig McNally Good to see them in the list. Previously could not find an API spec, or pointed to something outside of the folio-org repos.
- Zak Burke Mod-agreements still not there.
- Marc Johnson Because the code is not generated from the API documentation.
- Zak Burke So then that module doesn't exist from the POV of a developer. No way to find out the endpoints.
- Jeremy Huff Agree, hard to find if it's not listed on this page. Can also look to links from the repo.
- Craig McNally If Go RFC is approved, will those modules be listed here? If so will it be view-5? Are we making the problem even worse?
- Jeremy Huff If we do consolidate presentation and location, that implies that it would be complete. Absence here assumes there are somewhere else, pointed in docs?
- Marc Johnson Not always true. Modules that don't use the code generation approach, you don't have to write the API docs first so you can defer it. Or it can get out of date. Or might be using tools that don't line up with the centralized tooling.
- Marc Johnson We don't actually require documentation like this in our criteria. We require an application descriptor, but that's entirely separate.
- Maccabee Levine CQL details documentation. Standards differ between modules, questions come up all the time in #learning-apis.
- Marc Johnson Guide to what developers are supposed to do to write a module. Two levels. 1) Practical, how to use tooling to make life easier, set up a repo, etc. 2) Opinionated practices but not written down, beyond TC eval process. I.e. guide to how modules can be a good citizen in FOLIO-land. API conventions. Interface naming docs are out-of-date or actively misleading. Define these standards and conventions. Some we've baked into other tooling, like how some of the UI components are based around assumptions that APIs behave in a consistent manner in some regards, but those consistent behaviors were mostly quirks of the original modules and how RMB worked; some have gone over to Spring Way. I.e. you should supply total record count when you have a paged collection. So a module dev guide on how to be a good citizen.
- Jeremy Huff Encoding the conventions that have been adopted by the project, so devs pick the way that is more conventional from the project. New devs may not know, so we have a proliferation of alternate approaches to the same problem.
- Marc Johnson Yes, unwritten stuff accumulated over time. But recently, TC has started to standardize things, decision logs are good to describe why a decision was reached, but not help for a developer on how to use those decisions. Have to know about them, be able to find them. You really want a page that says to use RFC XXX date-time formats in a general piece of documentation, not in a random Jira issue / DL that no one knows exists.
- Zak Burke This is the guide stuff I was talking about.
- Marc Johnson <audio problems got lost>... If you want to build a module, it should do these things.
- Jeremy Huff I think of tutorials / walkthroughs. A useful guide would be a "zero to first commit" guide. Would be lengthy. Also documenting best practices, processes, could also be a guide. Not sure how best to differentiate.
- Marc Johnson Scope as Zak said: docs on environments, on what tools are available, and more general on how modules should behave to be a good citizen. Some of this stuff exists, check #devops for the number of times people point to a doc or explains some things are self-service. So some stuff exists, is just not stuff that folks find.
- Zak Burke Much of it is not available on that dev site, or buried there, or not clear how to maintain it. Also some of that doc info contradicts what we do on the UI side. How to drive people to the documentation, and have people responsible to know what is says and follow it. Docs scale in a way that people don't; they need to read through that site. People didn't know it was in the manual, or didn't bother to read it.
- Jeremy Huff Big part of advocate's work will be answering that question.
- Marc Johnson Back to the beginning, we don't have one manual (RTFM), we have many partial manuals. Have to remember the keywords you used to find the one page you want. Consolidation would be a great thing. So you can point folks to THE manual.
- Maccabee Levine Other devs adding to doc items to discuss?
- Olamide Kolawole Agree with what's been discussed. Difficulty in finding documentation, or it's not up to date. Taras agrees.
- Maccabee Levine Sysops documentation?
- Marc Johnson That may be a separate bucket. May be separate doc needs. How to run a FOLIO system in a production or near-prod sense, should be different from dev docs for building the thing. Is system operations docs also part of dev docs role?
- Jeremy Huff Agree, I was not thinking of sysops docs as part of the role. Seems to be a lot more shared knowledge in the sysops group than in the disparate dev teams.
- Maccabee Levine True. But sysops may have visibility to repeated questions from devs.
- Marc Johnson Within individual orgs like EPAM there is a lot of sharing. Probably true in other orgs. Sysops, probably a big distinction between hosting providers and self-hosters. So not everything may be shared everywhere. Self-hosters have a vested interest to share. It's a ton of work to run a production environment.
|