Where should uPortal documentation go?

6 views
Skip to first unread message

Benito Gonzalez

unread,
Jun 21, 2019, 1:31:52 PM6/21/19
to uPortal Developers, uPortal Community
Hi folks,

Reviewing documentation for uPortal, it is split between the old wiki, the uPortal repo and the uPortal-start repo. Creating and updating documentation should have a low barrier, so let's reduce this by making it clear where docs should go.

To start brainstorming, I have a few thoughts ...

- we should prefer uPortal-start over uPortal since most implementors and devs will have uPortal-start cloned/forked
- uPortal repo docs should link to uPortal-start, at the top of most doc pages for times when searching leads to such a page directly
- uPortal repo docs should target uPortal developers as their audience
- uPortal-start repo should target uPortal implementors, admins, UX designers, users, and service owners/managers
  - Might want to cut the docs across roles
  - Overlapping concepts should not be duplicated, but rather linked to a single doc
  - Implementors are operations folks that are tasked with running uPortal on servers or in the Cloud
    - concerns: integrations with enterprise systems, service configuration, network details
  - Admins are individuals with admin access, managing configuration via UI
    - concerns: data files, content management, user management
  - UX designers are technical folks that build out custom skins and layouts
    - concerns: skinning (CSS / Less), layouts, and maybe theming
  - Users: given the high degree of customization, their experience may vary greatly
    - concerns: how to log in, how to reset layout (for the few institutions that allow customizing layouts)
  - Service owners: people responsible for portal services at an institution
    - concerns: cost of ownership, security, performance impact to users, uPortal advantages over other options

Anyway, that's just what's been floating in my head of late. Please feel free to chime in!
--bjagg

Benito J. Gonzalez
Software Developer
Unicon, Inc.
Voice:  209.777.2754
 Text:  209.777.2754
Email:  bgon...@unicon.net
GitHub:  bjagg
GitLab:  bjagg
BitBucket:  bjagg


Jim Helwig

unread,
Jun 21, 2019, 1:40:09 PM6/21/19
to Benito J. Gonzalez, uPortal Developers, uPortal Community
Just a note that general uPortal project information (like links to the places to find documentation) will be migrating to the https://github.com/uPortal-Project/uportal-project.github.io repo (auto published at https://uportal-project.github.io/). With that in mind, if I understand what you are saying, there would be three main repos for documentation:

JimH
— 
Jim Helwig
Web Platforms & Services, UW-Madison

--
You received this message because you are subscribed to the Google Groups "uPortal Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to uportal-dev...@apereo.org.
To view this discussion on the web visit https://groups.google.com/a/apereo.org/d/msgid/uportal-dev/568596366.3660704.1561138310788.JavaMail.zimbra%40unicon.net.

Aaron Grant

unread,
Jun 21, 2019, 1:53:06 PM6/21/19
to Jim Helwig, Benito J. Gonzalez, uPortal Developers, uPortal Community
We've had this same discussion internally for many of our repositories. 

We ended up with this approach, we use markdown everywhere. We have documentation still on all repositories, however for discoverability we've created an index repository (in this case this could live on uportal-start) where we will give a small summary of an item and then link out to the master version of the document on its respective repo for more information. It's hard to get developers to update documentation that is not near the code, this seems to be the best outcome we've had so far. 

Downside of this approach is searching, if you have an attribute or something specific the index repo won't help you and you'll have to likely search the entire group of repositories to maybe find what you are looking for.



--
Aaron Grant
Associate Director Emerging Technology
Oakland University - UTS

Julien Gribonvald

unread,
Jun 24, 2019, 4:07:21 AM6/24/19
to uport...@apereo.org

Hi,

Aaron's feedback give a way, having doc near to the sources is required whereas developpers won't upgrade it.

To get an example CAS may have a good approach, the doc is global to all projects and at one place (a warning sometime we don't know on which project properties have a concern). I didn't watch exactly how the git doc repository was made but it's a linked (recursive) one inside cas project. Maybe we can have a such link inside several project ?

What to you think about this other approache ?


Julien

You received this message because you are subscribed to the Google Groups "uPortal Community" group.
To unsubscribe from this group and stop receiving emails from it, send an email to uportal-user...@apereo.org.
To view this discussion on the web visit https://groups.google.com/a/apereo.org/d/msgid/uportal-user/CAOsfLuT%3DNSgD%2BxiA3mcBrNyeSDRFENk%2Bv46ngZtU%3DB3-Ma4TgA%40mail.gmail.com.
--
Julien Gribonvald
Reply all
Reply to author
Forward
0 new messages