Ludovic Courtès <l...@gnu.org> writes:
> Hello! > > Ricardo Wurmus <rek...@elephly.net> skribis: > >> It would be great to have both! I’d like the existing reference manual >> to remain as the canonical description of all features of Guix, so that >> an additional story-centered document (whether that be a dedicated >> section or a separate file) can guide readers to more information if >> they might need it. > > I think it’s not all-or-nothing though. Our manual could be better > structured and it could include more examples. > > I like the “traditional” GNU manuals (libc, Emacs, Gnus, etc.), which > work very well for me, even though they’re only “locally > user-story-based”, so to speak. Yes, this can work. It’s hard for me to imagine where one would put prose that resembles a tutorial in our current manual. It currently leans very heavily towards a reference manual, which discourages me from adding elaborate examples. There’s also the danger of interrupting the flow with too many big inline examples. Currently, it is easy to understand the big picture because the prose isn’t separated by step for step instructions. It would be sad to miss out on good tutorials just because they don’t fit into the current manual; and it would be just as sad to clutter the manual by filling it with tutorials that would seem out of place. It’s difficult to strike the right balance. -- Ricardo
