Page Comparison

Technical Council Sub-Groups Updates

Static Code Analysis

• No update

Developer Documentation

• Meeting each week.  Patrick laying out the proposals well to be addressed.

Reminder(s)

• Go RFC still open - admin action required, only a PoC - nothing formal required other than closing the pull request.
• Still Need Decision Log record for application formalization, Go, configuration RFCs

From Slack:

Hi TC,

Can I request a 15-minute block of time for this coming Monday's meeting?

On behalf of the documentation subgroup, I'll propose a contribution model and best practices for community contributions to developer documentation. This is intended as a conceptual framework and not practical documentation, so to speak. That is, this document won't go in our documentation, but if approved, its propositions will be used for building such.

Please review the following in preparation for the proposal. And if you have any questions or anything, please let me or any member of the subgroup know. And feel free to comment on the document.

/wiki/spaces/DDG/pages/296157187

• Contribution Model.  Patrick Pace (Unlicensed): If approved, the model will inform other aspects of documentation, like the platform choice.  Encourage "courageous, healthy and productive communal contribution".  Based on Wikipedia's contribution model, not a copy but good place to start for OSS docs.  "We should be bold in editing", with enough people contributing it will end up being good over time.  Fluidity: continuing to evolve.  Cooperation, FOLIO already has a good culture of this.  Strategy: platform allowing for discussion, versioning and attribution; community needs to know about the model and how to contribute.  Best practices on editing, creating new documents.
  • Approved by lazy consensus
• Marc Johnson Where will the output of the documentation group live – policies, processes, etc.?
  • Patrick Pace (Unlicensed) No strategy on that yet, but the Developer Documentation Group space will continue to exist, it will live there.

From Slack:

Yesterdaythe developer documentation group decided on Confluence as documentation platform (Platform Comparisons,Platform Proposal- still rough draft -). The actual documentation work cannot start until the TC has approved this decision. To remove this blocker as early as possible I suggest to put this on Monday's agenda even if the proposal document is still in rough draft status.

Platform Proposal

• Patrick Pace (Unlicensed):  Documentation specific to modules should remain at GitHub.  Dynamic Documentation to remain at dev.folio.org, untill we determine that Confluence can house them and they can be moved.  Create a new Developer Manual in confluence.  Link the platforms as appropriate.
  • Structure of the Developer Manual to be proposed next week.  But will include general documentation that already exists, and new general documentation that is created.
  • Considered dev.folio, docs.folio, and Confluence.  Not proposing a single platform, because modules make sense at GitHub, and dynamic documentation seemed to need to remain at dev.folio, although that may turn out to be possible to migrate – at worst, we would like to it.
  • Why Confluence?  Just better for facilitating community contribution.  Developers can manage GitHub, but for any non-developer contribution, you would need specialists.  Reduce obstacles as much as possible.  Also:
    • Part of Atlassian, integration with Jira etc.
    • Precedence in community for documentaing htere.
    • Mature technology
    • Designed for community contribution
    • Lower overhead, no additional DevOps infrastructure.
  • Main caveats: existing developer documentation may remain at dev.folio.  Also dev.folio search includes GitHub content, that may not be possible in Confluence.
• Jeremy Huff Theoretically dev.folio.org is open to community contributions via GitHub, but historically it has not worked out like that.  From conversation with David Crossley, just a few individuals over the years have contributed.
• Marc Johnson
  • First, the dynamic documentation really doesn't below with the manual.  Two very different forms of documentation, only together per historical convenience.  Not very important to have them together.  Very different purpose.  Dynamic docs are for developers or sysops to know how the existing modules work.  Frustration with existing situation.  Different purpose to if you are developing something in FOLIO, guidelines on how you would do it.  There is a grabbag of docs on how to run the virtual boxes etc., that belongs somewhere else than how to develop stuff.
  • Re: concerns of people not doing anything with the dev.folio website, that's because there has not been encouragement to do so.  How we do that is presumably another part of the plan.
  • What would the transition plan be?  FOLIO has a history of making change decisions and then not having the capacity / priority to actually do it.  Causes significant drag in some areas, like two different doc specification technologies and two different frameworks.  Don't want to end up in the same position for this documentation.
  • Nice that these proposals are coming through in manageable chunks.  We might have similar challenges to Eureka with packaging stuff into small pieces, might be hard to be cohesive at the end.
  • Seems slightly odd that as a technical audience we're moving to a wiki and may want non-technical folks involved, and yet product documentation folks actively chose not to use a wiki and to train people to produce that documentation.  Worth considering overall cohesion.  Don't know if regular releases will be part of this documentation plan.
• Patrick Pace (Unlicensed) 
  • Re: dynamic documentation, this gets into the structure proposal coming up.  Will be linked to in the references section of the manual, not the main content.  Could make adjustments to incoordinate it directly, but if not, should just be named in the manual / indicate that it exists.
  • Transition plan?  There is a plan being developed (#8 Documentation Consolidation Plan).  This will be a big project, will need to have enough gas in the tank to keep it going.  Can't put everything on one person like David Crossley, so it can continue to live until it's done.  But still being developed.
  • How do we know if it's cohesive?  List of lots of pieces and how they fit together.  The Proposals document.  They do depend on each other.  TC approving one means we can move onto the next.  Lots of connections between them.  
  • Docs WG not using the wiki?  Didn't talk to the Docs group about that but did talk to David Crossley, and the wiki didn't exist when they started dev.folio, and someone else chose that platform, David inherited it. 
    • The Releases capability of docs.folio, how do we handle that for developer documentation?  If needed, could package it up.
• Craig McNally If the dev site searches GitHub (and maybe the wiki also), there might be a Confluence plug-in that does something similar.
  • Jeremy Huff  agrees.
• Maccabee Levine agrees the proposals are cohesive, and with Patrick's other answers.
• Approved by lazy consensus.

Officially Supported Technologies (OST)

• Maccabee Levine Is this the same as the PC subgroup working to improve sample data?
  
  • Marc Johnson Not sure.
  • Tod Olson Thought we were taking about the same thing as the group a lot of people were on for a while.
  • Craig McNally Reference data working group a couple years ago is what sysops is taking about.  Not sure if it's the same as the sample data group.
  • Tod Olson Was much more involved the last time.
  • Maccabee Levine Just make sure the two groups are aware of each other.
• When Ingolf Kuss returns, can get more info.
• Tod Olson This new PC group is about sample data.  Years ago data was contributed.  Now new functionality, there are no sample data test cases.
• Maccabee Levine Example, in snapshot there are no orders connected to any invoices.
• Tod Olson Reference data can be customized (i.e. material types) or added to, but often is not.  Some stable conventions are needed for the reference environments.  It's a fuzzy boundary.
  • Craig McNally System data is a third category.