Re: [uportal-dev] Where should uPortal documentation go?

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

Re: [uportal-dev] Where should uPortal documentation go?

Julien Gribonvald

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


Le 21/06/2019 à 19:52, Aaron Grant a écrit :
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]> wrote:
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

On Jun 21, 2019, at 12:31, Benito Gonzalez <[hidden email]> wrote:

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
[hidden email]
GitHub:  bjagg
GitLab:  bjagg
BitBucket:  bjagg



--
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 [hidden email].
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.

--
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 [hidden email].
To view this discussion on the web visit https://groups.google.com/a/apereo.org/d/msgid/uportal-dev/13A705C0-4489-497C-8834-E81A36876B76%40wisc.edu.


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

--
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 [hidden email].
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

--
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 [hidden email].
To view this discussion on the web visit https://groups.google.com/a/apereo.org/d/msgid/uportal-user/1d76ab21-84aa-5d6f-bdf5-2e38118536e0%40recia.fr.