portal 4.0.0 functionality described in portal_config.md #1097
Conversation
docs/portal_config.md
Outdated
| @@ -481,6 +501,23 @@ Below is an example, with inline comments describing what each JSON block config | |||
| "tagSelector": { | |||
| "title": "Associated tags organized by category" | |||
| }, | |||
| "studies": [ // new in data-portal 4.0.0, this configures addition of tutorial nbs to specific studies. Shown here in BRH example. For HEAL, set to [] | |||
There was a problem hiding this comment.
can you elaborate a bit more about how this canbe used? with those match and fieldsToValues?
There was a problem hiding this comment.
IMO, the level of detail you are requesting is easier to communicate via code than documentation (e.g. someone needing to know more detail than the example can look at the data portal code)
There was a problem hiding this comment.
yeah true but the code is lack of comment as well 🤦 And while we can improve documentation now, why wait?
we should try our best to not make information silos to devs who write the code
There was a problem hiding this comment.
if you think it will be too verbose to put in this file, you can write a dedicated markdown like https://github.com/uc-cdis/data-portal/blob/master/docs/ecosystem_browser.md
There was a problem hiding this comment.
Code doesn't always need to have comments and usually should be self documenting. Excessive documentation makes maintenance more tedious.
And while we can improve documentation now, why wait?
Because the anticipation of a BRH go live has been going on for months and the team may finally have enough momentum for it to actually happen.
we should try our best to not make information silos to devs who write the code
Putting an emphasis on writing clean, self documenting code instead of excessive standalone documentation is actually a win-win for product managers and developers: encourages product managers to look at source code and obviously makes the job more fun for a developer.
There was a problem hiding this comment.
Excessive documentation makes maintenance more tedious.
Agreed. But I don't think the ask is excessive. If a ppl needs to go back to the original PR or code base checks among 100+ lines of changes to figure out why my portal is crashing because of missing a [] in config file or understand why the matches working from a config file doesn't work for another one, how is that code "clean and self documenting"?
encourages product managers to look at source code
Good thinking. But you cannot expect all PMs have the same level of understanding of code as devs. This is just unrealistic. And PMs and Devs are not the only person who will update portal configs to deploy a new feature
There was a problem hiding this comment.
Hey guys, I'll add some more documentation to this. May not be today, but definitely soon. I think we need a good balance of clean code and documentation, so I'll go over that and try to fill the gaps as needed. Portal is very new to me as well, so may be a good starting point to see if I can make it such that anyone can follow.
|
i adjusted the comments a little so we can add some documentation to the code base, it would be better if it gave some idea of how to use it (code is not self documenting and has 0 comments). but since this has been sitting for 8 months i would rather get something merged, this documentation should have been part of original PR that added code |
Jira Ticket: PXP-xxxx
New Features
Breaking Changes
Bug Fixes
Improvements
Dependency updates
Deployment changes