On Thu, Jun 8, 2017 at 7:15 PM, Tom Hughes <tom@compton.nu> wrote:
On 08/06/17 17:58, Matthew Miller wrote:
On Thu, Jun 08, 2017 at 10:38:11AM -0500, Michael Cronenworth wrote:
Normally I ignore any Modularity discussion. It doesn't interest me,
and it doesn't affect any projects I work on. It's my own fault that
this change, which does affect me, was not on my radar. I'm not
looking to stop the change but only express my concern about the
lack of marketing and lack of documentation.

Thanks. Communication is hard. Have you seen the stuff at
https://docs.pagure.org/modularity/?

Speaking for myself I came across that the other day and got as far as clicking through to the documentation page and seeing that just the contents was about four screens long and gave up at that point as it's not something I have much interest in anyway.

Something similar happened in regard to the specific issue here when comment was invited on the arbitrary branching stuff before Fesco discussed it in that I clicked through to the document and found it was a long and detailed list of steps the sysadmins would need to take to roll it out rather than an explanation of what it meant for end users and gave up at that point on trying to understand what it meant beyond moving from pkgdb to pagure over dist-git.

This is actually a good feedback. The landing page should explain the main concepts and the documentation should give more detail... but maybe the landing page is very high-level and the docs too detailed? And there is nothing in between?

I talked to someone about a different way to write stuff - starting with a summary at the top and giving more and more details as you follow reading. But you could theoretically stop reading at almost any point and it should still make sense. Maybe I could give it a shot and rewrite some of the pages - or at least give a higher-level, yet still specific and technical, summary. Hmm.. let me think about it.

Suggestions? Anything I should prioritize?
 


Tom

--
Tom Hughes (tom@compton.nu)
http://compton.nu/

_______________________________________________
devel mailing list -- devel@lists.fedoraproject.org
To unsubscribe send an email to devel-leave@lists.fedoraproject.org



--

Adam Šamalík
---------------------------
Software Engineer
Red Hat