documentation suggestions

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

documentation suggestions

Trenton D. Adams
Hi Guys,

All of this is related to CAS 5.2.x

I've noticed that the CAS documentation consistently links to other
documents with the words "review this guide".  Without a proper noun, it
is impossible to know what "this guide" is when viewing the
documentation from a printed document.  For example, running the command
below on the CAS markdown generates a nicely formatted pdf document of
all the configuration management documents.  But, since it just says
"this guide" I'm like "what guide exactly?"

pandoc --toc -Vpapersize:letter -Vmargin-left:1in -Vmargin-right:.5in -f
markdown -t latex -o cas.pdf installation/Configuration-Management.md
installation/Configuration-Server-Management.md
installation/Configuration-Properties-Common.md
installation/Configuration-Properties-Security.md
installation/Configuration-Metadata-Repository.md
installation/Configuration-Management-Extensions.md
installation/Configuration-Management-Extensions.md
installation/Configuration-Management-Reload.md
installation/Configuration-Management-Clustered.md
installation/Configuration-Discovery.md; google-chrome cas.pdf

Another thing I noticed is that there always seems to be a small
disconnect in all of the CAS documents I've seen, which makes them
difficult to follow when you don't expect that.  I spent many hours
asking questions like "Is the documentation not complete?", "What is it
that I'm missing?", etc.  When documentation is disconnected like that,
it becomes difficult to maintain context in your brain.  I ended up
finding that the documentation is actually quite good, it's just got
some disconnect in it.  As soon as you click a link to another document,
your brain says "I'm somewhere else now, on a different topic, and I
don't need the other information I was looking at".  So, in essence you
have to purposefully choose to maintain context.  Now that I know how
it's all organized, I get it, and I can choose to maintain the context
in my head.

As an example, let's take the LDAP authentication module.

https://apereo.github.io/cas/5.2.x/installation/LDAP-Authentication.html

In the above document, it says almost nothing except what to include in
your pom, and there is a link to relevant cas properties document.  The
CAS properties document is not a CAS properties document at all, it's a
"document everything" document.  It does seem that it would make more
sense for every module to have either it's own document with everything
related to that module.  Given that the "properties" document right now
is a document for everything, another alternative might be to have a
single document for authentication related stuff, including properties,
with an overview, and with a section for each module.

If instead the LDAP-Authentication document is included at the top of
the LDAP documentation in the properties document, and that
documentation as a whole is moved to it's own document, the
documentation then just flows, especially when printed.  That actually
leads to an important documentation concept: if I were to print this
documentation, would each unit of documentation be mostly understandable
as a whole, or do I have need to manage which documents I print and in
what order I print them to understand?".  I created this new document as
an example of how it now has that "flow".

The pdf was generated with...

pandoc --toc -Vpapersize:letter -Vmargin-left:1in -Vmargin-right:.5in -f
markdown -t latex -o cas.pdf LDAPAuthentication-General.md

Take note that for the most part I have changed nothing about the
documentation except some structural things, as the documentation itself
is quite good.

Lastly, there is one thing missing from my version of the document.  It
would need to link out to a document that explains how CAS configuration
works in general terms; things like cas.properties,
application.properties, application.yml, etc.



--
Trenton D. Adams
Senior Systems Analyst/Web Software Developer
Applications Unit - ITS
Athabasca University
(780) 675-6195

It is only when you are surrounded by a supportive team, that you can achieve
your best.  Instead of tearing people down, try building them up!

--
This communication is intended for the use of the recipient to whom it is addressed, and may contain confidential, personal, and or privileged information. Please contact us immediately if you are not the intended recipient of this communication, and do not copy, distribute, or take action relying on it. Any communications received in error, or subsequent reply, should be deleted or destroyed.
---

--
You received this message because you are subscribed to the Google Groups "CAS Developer" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/cas-dev/.

cas.pdf (246K) Download Attachment
LDAPAuthentication-General.md (16K) Download Attachment