Re: [uportal-dev] Where should uPortal documentation go?
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 ?
Le 21/06/2019 à 19:52, Aaron Grant a
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.
On Fri, Jun 21, 2019 at 1:40
PM 'Jim Helwig' via uPortal Developers <[hidden email]>
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
- 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
- uPortal repo docs should target uPortal
developers as their audience
- uPortal-start repo should target uPortal
implementors, admins, UX designers, users, and
- 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,
- 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
- concerns: how to log in, how to reset
layout (for the few institutions that allow
- 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!
Benito J. Gonzalez
Text: 209.777.2754 [hidden email]