Notes 27/11

[Nicola Nye]

Summary of feedback from the Write the Docs doc sprint last Friday.
http://www.writethedocs.org/conf/au/2017/

As mentioned, I had two users I was talking with. One is a technical
writer and used to dealing with subject-specific terminology but  had
no experience with mail systems. The other is an engineer who
currently runs Dovecot for a side project and thinks he might have
used Cyrus in the past.
*Front page*
Wall of text and acronyms. Intimidating.

 * Pull in content from the github readme that explains in simpler
   language what Cyrus is
 * Some images to break up the text and reinforce that Cyrus supports
   not just mail, but calendaring and contacts on mobile too.
 * Showcase places that Cyrus is being used. (If you're happy for your
   organization name to appear in the docs, please let me know!
   Optional: send me a logo and a link) This helps distinguish Cyrus as
   mail software, not a mail hosting service.
 * If there's anyone who does professional services support for Cyrus,
   make sure they're listed. (anyone? anyone?)
 * Explain target profile. "You want to run Cyrus if you want these
   features, and you have this many mailboxes/users and you know what
   you're doing with running/supporting a mail system. You do not want
   to run Cyrus if: ..."
*Navigation*
The top navigation bar confused users. They were expecting dropdown sub
menu, but then there's also the left menu.
 * The top menu bar no longer needs to be there. It's a hangover from
   when the left hand menu bar was a maze of twisty passages all alike
   and I wanted a way to quickly help users find common entry points.The search box was overlooked.
 * I might make this bigger and/or put it in the top menu bar as the
   only thing.Confused by left hand menu ordering.
 * They both expected the Overview to come first, followed by
   Quickstart, then Download, then Setup.
 * They did like the categorization of the top level menu hierarchy.
   Easy to drill down one level.
 * Second level and beyond menu items were intimidating in many places.
   Again, technical overwhelm.
*Content*
 * Cyrus is not a complete solution on its own: you need other system
   components (MTA: sendmail/postfix/exim/..., possibly webmail
   interface).
 * Both users went looking for system requirements and couldn't find a
   succinct list. I'll need to write this. (including content from the
   above point)
 * They wanted to know if it could be run on vmware (or equivalent) or
   cloud hosted.
 * Overview was deemed too technical.
   * The Overview/Features section was just okay
   * The Overview/Concepts section was more of a reference manual than
     an explanation of ideas: need to review and split this apart.
The documentation has plenty of ways to evolve! If anyone is interested
in helping out, do let me know.
And if you know of anyone who
 * does professional Cyrus support, or
 * uses Cyrus and is happy to have that listed on our sitedrop me a line and I'll put you in.

Cheers,

    Nicola

On Mon, Nov 27, 2017, at 10:26 PM, Bron Gondwana wrote:
> Present: Bron, Ken, Nicola, ellie
> 
> Bron:
> * Lots of Xapian issues last week
> * including seqset bug
> * incorrect UID issue for per-user-data only updates with calendar
>   events.> * index_snippets is keeping the mailbox locked while reading from disk
>   and generating snippets, which can be slow and block out other
>   actions.  We should find a solution to this.> 
> Ken:
> * working on docs for internals changes - sync, rename safety etc
> * SASL - looks like Alexey is correct, and people were relying on
>   buggy behaviour> * found a logic error with Bearer Token authentication.
> * short week this week
> 
> Nicola:
> * went to write-the-docs on Friday, single day conference
> * didn't fix any doc bugs
> * had people with mail server knowledge
>   - used them as guinea-pigs to look at our existing docs
>   - have notes which will write up and send to list
>   - if you don't already know what Cyrus is and how it works, it's a
>     wall of acronyms>   - FastMail webpage was the kind of thing he was expecting - but at
>     least Cyrus docs look better than Dovecot!> * FastMail caldav sync doesn't handle alarms particularly nicely.
> * Also, FastMail caldav sync should be copy through calendar-user-
>   address from the source and passing that through for clients to use
>   for scheduling.> 
> ellie:
> * just been looking into the jmap getmessagelist stuff -- that email
>   thread today is v useful> 
> sasl is just a point release, so should be safe to upgrade
> independently> 
> Partha is back working on zeroskip after being involved in the xapian
> fixes most of last week.> 
> --
>   Bron Gondwana, CEO, FastMail Pty Ltd
>   brong at fastmailteam.com
> 
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20171128/0068bb11/attachment.html>