[sakai-pmc] Review 10.4 documentation?

Thu Feb 19 06:47:21 PST 2015

I asked for feedback, and by nature that often can come across as negative,
but that's okay.

For now, what I did was remove the "Created by..." completely. We can add
back in if necessary but doesn't seem like it belongs there.

I made the page formatting more consistent. I still have more work to do to
make the content consistent, and perhaps additional tweaking to the
formatting (or not, maybe simpler is better, which is the approach I took).

http://sakaiproject.org/current-release

To me, the bigger issue who are we targeting with these pages.  I think we
should have one page (or area) for technical folks and one page (or area)
for everyone else, in plain non-techie English. So, I'm wondering if we
should not have ANY technical documentation on www.sakaiproject.org and
point everyone back to Confluence Release notes which we keep pretty up to
date and have multiple translations! But even removing this stuff from
www.sakaiproject.org will take thoughtfulness and beyond what we can
probably do right now.

However, we have multiple places on www.sakaiproject.org to get updated
which is error prone and makes more challenging for consistent formatting
and content.

For example, if you look down on
https://www.sakaiproject.org

There is a section that is almost exactly like the current-release page. So
things can be right on one page and wrong on another (formatting and
content).

But, that's life for now. Maybe at a later date we can reorganize things,
or start moving to Github pages and find ways to reuse content. If anyone
has ideas on how to do this the best way, that could be helpful.

Possible to-dos still (from Sam and Steve suggestions):
* Review where should the mention of  Tomcat 7.0.56+ up and JDK 1.7.0_76
issues? They are on Confluence and source.sakaiproject.org/release/ and
maybe also need to go on the current-release page and not on the top
www.sakaiproject.org page, because current-release seems to contain more
technical documentation.

* Still maybe need to add a prominent link to Release notes  from the Press
release page.

On Thu, Feb 19, 2015 at 5:04 AM, Steve Swinsburg <steve.swinsburg at gmail.com>
wrote:

>
>    - The tagline 'Created by and for a global education community' is
>    formatted weird and seems out of place.
>    - Heading 'Whats new in 10.2' is different style to the others.
>    Likewise with 10.0.
>    - List of items in 10.4 is all bold and grey, different in 10.1 and
>    10.0 where its bolded then has a normal weight description.
>    - 10.0 and 10.1 has a bulleted list of items, 10.2 onwards does not
>    and the spacing is different.
>    - Maybe add a prominent link to the page from here?
>    https://www.sakaiproject.org/sakai-10
>
> Sorry, all seems negative, but some styling has gone amiss somewhere which
> is breaking that page. Once that's sorted, its just content.
>
> I do agree that a specific number of fixes is better though. If its out by
> an issue or two because of a badly tagged jira then it doesnt matter, no
> one is going to sue us, but the words do matter in terms of presenting the
> data.
>
> cheers,
> Steve
>
> On Thu, Feb 19, 2015 at 7:52 AM, Neal Caidin <neal.caidin at apereo.org>
> wrote:
>
>> I fixed things based on most of your suggestions.
>>
>> I'm not sure, but I might have a slight difference of opinion on a couple
>> of your suggestions.
>>
>> >"about 50 fixes"
>> The reason I often revert to this is because the exact count is hard to
>> pin down, in reality. Some things are not tagged that are in the release.
>> Occasionally (but more rarely) something that showing is merged really
>> hadn't been, and often, though not for this release, Security issues we
>> could be counted that most users don't see. To me, about 50 fixes is not
>> vague and is clearly distinguished from about 200 fixes for example. Those
>> numbers, imo, give the order of magnitude of the number of fixes. But, I
>> might be getting a little to uptight about the details there. I changed it
>> to a specific number.
>>
>>
>> > The link to the issues fixed should be in all communication.
>> I think of different communication channels as having different needs. I
>> agree the technical details should be on source.sakaiproject.org and on
>> our Confluence wiki release notes. I'm not as sure that they should be on
>> www.sakaiproject.org and on an email announcement to Apereo
>> Announcements or other non-technical lists. I'm thinking for those lists a
>> high level accounting of what you all accomplished is sufficient. But that
>> is just my opinion.
>>
>> In summary, I'll try and remember to use the specific number instead of
>> "about 50" though it goes slightly against how I think of it, but no big
>> deal. It would be nice to come to a consensus on the communication channel
>> thing. And, I'm thinking I should probably slow down by 1/2 day and give
>> PMC/Core team a chance to review communications before I send them (which I
>> have been inconsistent about, I admit).
>>
>> Thanks!
>>
>>
>>
>>
>> On Tue, Feb 17, 2015 at 3:23 PM, Sam Ottenhoff <ottenhoff at longsight.com>
>> wrote:
>>
>>>
>>>>
>>>> Always nice if I can get a second pair of eyes to review the
>>>> documentation:
>>>>
>>>>
>>>>    - http://sakaiproject.org/current-release
>>>>
>>>>
>>> What's new in 10.4?  "Bug Fixes."  Please be specific with a number (not
>>> "about 50") and provide a link to those bug fixes.
>>>
>>> Tomcat is 7.0.56 not 7.056
>>>
>>> "compatibily" spelling
>>>
>>> Sakai 10.4 has a few highlights that are in your release notes.
>>> Simplified Chinese and Admin Documentation are not the core highlights.
>>>
>>> Please fix the headings.  They are inconsistent especially "What's new
>>> in Sakai 10.1"
>>>
>>>
>>>
>>>>    -
>>>>    and of course, the standard
>>>>
>>>>    https://confluence.sakaiproject.org/display/DOC/Sakai+10+Release+Notes
>>>>
>>>>
>>>
>>>
>>> The recommendation for Tomcat 7.0.56+ up (because of WebDAV, I believe)
>>> and JDK 1.7.0_76 are pretty crucial and should be included in all
>>> communication about this release.
>>>
>>> The link to the issues fixed should be in all communication.  Your email
>>> to apereo-announce seemed vague ("about 50 fixes" with no list of fixes or
>>> link to fixes).
>>>
>>
>>
>> _______________________________________________
>> sakai-pmc mailing list
>> sakai-pmc at collab.sakaiproject.org
>> http://collab.sakaiproject.org/mailman/listinfo/sakai-pmc
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-pmc/attachments/20150219/4f01dd2f/attachment.html 