For anyone else not familiar yet with the "bus factor", I learned from wikipedia that "The bus factor is a measurement of the risk resulting from information and capabilities not being shared among team members, derived from the phrase "in case they get hit by a bus."
/c On Tuesday, March 1, 2022 at 2:49:12 AM UTC-6 [email protected] wrote: > Furo looks good. If you think the bus factor is not a big deal, that's > fine then. It's not as important as an actual dependency of sympy. > > > The decision to use Furo isn't completely final yet. So if you want to > make the case for one of the other themes, you still can. > > My vote in the survey was RTD. I explained it in the survey my reasoning. > But that's all I have to offer for the case. > > Jason > moorepants.info > +01 530-601-9791 <(530)%20601-9791> > > > On Tue, Mar 1, 2022 at 12:50 AM Aaron Meurer <[email protected]> wrote: > >> On Sat, Feb 26, 2022 at 1:11 AM Jason Moore <[email protected]> wrote: >> > >> > Thanks for doing this! I read through all the comments. >> > >> > Couple of points: >> > >> > - With 22 respondents and large standard deviation, the numbers don't >> really mean anything. Basically all themes are rated the same. >> > - The written comments are most useful and I get the impression that >> almost any of the themes could work, but each requires some tweaking to fit >> for SymPy. >> > >> > I would recommend choosing based on which theme has the most >> configuration options and energy behind it because we want to easily tweak >> things and we automatically benefit from upstream improvements. If we do >> pydata, we join with our counterparts Numpy, scipy, pandas, etc. and it >> keeps us connected nicely to that community and when people jump around the >> scipy ecosystem docs they get the same (or similar) experience. RTD theme, >> by far, is the most used because it is the default theme on their service >> and there is a company that spends a lot of dev time on it. RTD is quite >> valuable and gives a uniform experience across a large set of python >> projects. Furo and book are likely used the least and have the smallest dev >> communities. Furo, as I understand, is essentially a one man show. It looks >> nice now, but may not be a good long term solution. >> >> I agree that the bus factor is a downside to Furo. However, I'm not >> too worried about it given that it's not all that hard to change the >> Sphinx theme. Any customizations would have to be redone, but it took >> me about a day of work to restyle Furo (and honestly someone more >> familiar with CSS could have done it much faster). And there are ways >> that Furo could have made restyling easier than it was, so potentially >> restyling a hypothetical future theme could be done even easier. >> >> The styling (colors, font choices, very basic CSS changes) are easy to >> make. What's hard to do is to change how the theme works at a >> fundamental level. That's why one of the primary things we looked at >> was the behavior of the sidebars in the different themes. This is not >> something we can "fix" ourselves with some CSS. We are really just >> stuck with however the theme handles things. Here Furo had the best >> behavior: for instance, the right sidebar always being expanded, which >> was noted in the survey as a plus. I would like to avoid things like >> custom Javascript on the docs site, as it becomes unmaintainable given >> that most SymPy developers are not frontend developers. >> >> In general, the Furo theme seems to have had a finer attention to >> detail than the other themes. We have a lot of docs and they exercise >> a lot of corner cases that the other themes don't seem to have been >> designed around, but Furo handles them correctly. As an example, look >> at how the different themes' sidebars handle the very long section >> names on the active deprecations page. Book and Pydata add a >> horizontal scrollbar to the sidebar: >> >> >> https://bertiewooster.github.io/sympy-doc/book/explanation/active-deprecations.html#sympy-stats-discretemarkovchain-absorbing-probabilites >> >> https://bertiewooster.github.io/sympy-doc/pydata/explanation/active-deprecations.html#sympy-stats-discretemarkovchain-absorbing-probabilites >> >> Readthedocs just truncates the long names: >> >> >> https://bertiewooster.github.io/sympy-doc/rtd/explanation/active-deprecations.html#sympy-stats-discretemarkovchain-absorbing-probabilites >> >> Furo word wraps the text: >> >> >> https://bertiewooster.github.io/sympy-doc/furo/explanation/active-deprecations.html#sympy-stats-discretemarkovchain-absorbing-probabilites >> >> The Furo behavior is clearly the best, and it suggests to me that the >> other themes were not ever tested on this sort of thing. >> >> > >> > Jermey and Aaron concluded that Furo was the best choice, but I hope >> these other aspects are considered too. We're a big project and even if >> Furo currently has the best looking design of the four, there are other >> non-design factors that are also quite important and, IMO, outweigh the 0.1 >> point rating differences in the comparison of the designs. >> >> The decision to use Furo isn't completely final yet. So if you want to >> make the case for one of the other themes, you still can. >> >> Aaron Meurer >> >> > >> > Jason >> > moorepants.info >> > +01 530-601-9791 <(530)%20601-9791> >> > >> > >> > On Sat, Feb 26, 2022 at 1:24 AM Jeremy Monat <[email protected]> wrote: >> >> >> >> Hello SymPy community, >> >> >> >> SymPy ran a user survey about its documentation theme from February >> 5-19, 2022. The primary purpose of the survey was to guide the selection of >> a Sphinx theme for the SymPy Documentation at https://docs.sympy.org. We >> thank everyone who took and shared the survey. >> >> >> >> Even though the survey is no longer open, we still welcome feedback on >> SymPy's documentation. Feel free to reach out to us on the mailing list, or >> in the Github issue to change the Sphinx theme. >> >> >> >> I have written up an analysis of the results at >> >> https://www.sympy.org/sympy-docs-survey/2022-theme-survey.html >> (thanks to Aaron Meurer for some analysis code, and posting the analysis >> there). The source code for the >> >> Jupyter notebook can be found at >> https://github.com/sympy/sympy-docs-survey. I >> >> have included a summary of this analysis here. >> >> >> >> A total of 22 people responded. The survey was done on Google Surveys >> and was shared on the SymPy public mailing list, the @SymPy Twitter >> account, and a SymPy discussion on GitHub. The survey consisted of 14 >> questions, all of which were optional. The results of these responses are >> summarized here. We would like to thank everyone who took and shared the >> survey. >> >> >> >> At a high level, there are three main takeaways from the results. >> >> >> >> The themes can be divided into three ratings categories, where the >> rating scale was 1 (Not very useful) to 4 (Very useful): >> >> >> >> Highest: Furo at 2.95. >> >> Middle: PyData and Book, nearly tied at 2.85 and 2.86, respectively. >> >> Lowest: Read the Docs (RTD) at 2.47. >> >> >> >> Most comments about themes, both likes and dislikes, were about >> formatting, look and feel, and navigation. >> >> >> >> We should proceed with the Furo theme, customizing it to address >> respondents' dislikes about its formatting. We can keep the PyData and Book >> themes in mind as backup options. >> >> >> >> Again, I would like to thank everyone who took the time to fill out >> this survey. It really helps us to have your feedback. >> >> >> >> Jeremy Monat >> >> >> >> -- >> >> You received this message because you are subscribed to the Google >> Groups "sympy" group. >> >> To unsubscribe from this group and stop receiving emails from it, send >> an email to [email protected]. >> >> To view this discussion on the web visit >> https://groups.google.com/d/msgid/sympy/ae6935a1-d638-4265-a094-bd59f1dfc643n%40googlegroups.com >> . >> > >> > -- >> > You received this message because you are subscribed to the Google >> Groups "sympy" group. >> > To unsubscribe from this group and stop receiving emails from it, send >> an email to [email protected]. >> > To view this discussion on the web visit >> https://groups.google.com/d/msgid/sympy/CAP7f1Aidk%3DK_hNciDukWPUM4V6hUNxZXDMkQm-%3DMnR5WcnNspA%40mail.gmail.com >> . >> >> -- >> You received this message because you are subscribed to the Google Groups >> "sympy" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to [email protected]. >> > To view this discussion on the web visit >> https://groups.google.com/d/msgid/sympy/CAKgW%3D6%2BUOV6t%3DgYFqsSxpOs3XuhrtskhFJ0WC_SBMHm2-tvobQ%40mail.gmail.com >> . >> > -- You received this message because you are subscribed to the Google Groups "sympy" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/94987327-7337-4386-bd6f-112dd5713d97n%40googlegroups.com.
