On Thu, Sep 29, 2022 at 12:41 AM Bryce Harrington <bryce.harring...@canonical.com> wrote: > > On Wed, Sep 28, 2022 at 10:27:27AM -0700, Lena Voytek wrote: > > Hello all, > > > > As I finish up the preparations for the Server Guide to transition to > > diataxis, I was wondering if I could get your feedback on a few items. > > > > The first is the new home page. I created a page for its proposal here > > <https://discourse.ubuntu.com/t/proposed-ubuntu-server-guide-homepage-using-diataxis/30895> > > (excluding the full navigation section), and can move its contents over to > > the current home page <https://ubuntu.com/server/docs> next, which will > > automatically update the guide's navigation. It's meant to match the > > standard > > homepage documentation > > <https://docs.google.com/document/d/1Zw-UoQzHMSQjATLXjjvd9GKu5qU2mHmqxtKck8nGkbU> > > as closely as possible, similar to Ubuntu Core > > <https://ubuntu.com/core/docs>. If there is anything that can be worded > > better, or that is missing and should be there let me know! > > > > Second are the diataxis home pages: Tutorials > > <https://discourse.ubuntu.com/t/ubuntu-server-tutorials/29948>, How-to > > guides <https://discourse.ubuntu.com/t/ubuntu-server-how-to-guides/29950>, > > Explanations > > <https://discourse.ubuntu.com/t/ubuntu-server-explanation-guides/29951> and > > Reference <https://discourse.ubuntu.com/t/ubuntu-server-reference/29949>. > > These are meant to be similar to Ubuntu Core's sections: Tutorials > > <https://ubuntu.com/core/docs/tutorials>, How-to > > <https://ubuntu.com/core/docs/how-to>, Explanation > > <https://ubuntu.com/core/docs/explanation>, and Reference > > <https://ubuntu.com/core/docs/reference>. > > > > Lastly I would like your opinion on formatting for some of the existing > > server guide pages. Many of our pages focus on individual packages, and > > while doing so contain portions that vary in terms of what part of diataxis > > they fall under. For example, in the Squid page > > <https://ubuntu.com/server/docs/proxy-servers-squid>, the first two > > paragraphs are an explanation, followed by the Installation and > > Configuration sections which are technically tutorials, and ending with the > > References section which of course falls under reference. There are two > > main options I could move forward with here. The first would be to split > > the page up to purely match diataxis, possibly adding some more depth to > > the explanation, while creating a new page specifically as a tutorial for > > installing/configuring the package. The second would be to leave the page > > as it currently is and mark it as a reference. This would likely be easier > > for users to follow since they would be able to reference all important > > information about a given package without going to multiple pages. This > > change would affect most single-page packages in the Services and Tools > > section of the guide. Larger guides, however, such as OpenLDAP > > <https://ubuntu.com/server/docs/service-ldap-introduction>, can be split > > much more cleanly by page between the four categories. > > Hi Lena, first thanks for all the work and attention on this. The > restructuring work here looks overwhelming but you've given good though > into how it can be organized. > > I don't have a deep knowledge of Diataxis, basically just a read-thru of > https://diataxis.fr/ coupled with past experience with doc writing. > Hopefully these thoughts aren't too far misaligned to be of use. > > Wearing the hat of a server user that would be consuming these different > kinds of documents, and thinking about what currently exists in the > Ubuntu Server Guide, honestly none of it matches what I'd expect as > "Reference". To me, "reference docs" for server stuff would be way more > akin to man pages and --help text; I would not be unpleasantly surprised > to find in Reference copies of upstream's reference docs, reformatted > for Ubuntu's website (along the lines of readthedocs.org). Much of what > we currently have is too piecemeal and narratively structured to be what > I would consider proper reference. In particular, the lists of > "reference" links to external resources to be "Reference Documentation"; > they are more just "See Also" links. > > Honestly I don't think the Server Team is really contituted in a way > that lends itself to writing and maintaining reference documentation, > with the exception *maybe* of software Canonical develops and maintains > itself like Curtin. > > So for the Reference section, I kind of am of the mind that this section > should start empty and maybe should be populated by auto-generating what > the upstream provides in the versions of packages included in the given > LTS release. As a user, having all the upstream docs reliably gathered > together in one place, with consistent formatting (and maybe even > cross-referencing!) would be a big value-add. > > > To me, the authorial intent of the Ubuntu Server Guide aims to something > in between Tutorial and How-To, with most pages leaning more towards the > former than the latter. I might even go so far as to suggest that all > the current pages be put into Tutorials and then go through one-by-one > and extract any text that narrowly focused and discrete enough to exist > as a How-To. > > I haven't read everything in the Server Guide, but I have a feeling very > little in there would really qualify as "Explanation". To me, > Explanation docs would address the "Why" and not the "How", and focus > more on matters of policy decisions or in-depth theory behind services. > I could be wrong but I think there's little in the guide currently that > delves into this. I would imagine this section should read more like > our debian/README files, particularly where there are Ubuntu-specific > info. So for example, I would enjoy seeing topics like these in > Explanation: > > - Why does Ubuntu carry only a single version of PHP|Ruby|etc. in a > given release? > - Why does Ubuntu support multiple of the same kind of software? > E.g. why both apache2 and nginx? Why both mysql and postgres? etc. > - Why we make services start automatically on installation > - What can I expect to happen to my services during an LTS-to-LTS > upgrade? > - What happens to user's custom service configurations on upgrade > - Why does Ubuntu not follow a rolling-release model, and what are my > alternatives and considerations for staying up to date > - What should I keep in mind when designing my data center using > Ubuntu Server components? > - Why should I use mysql over postgres or other databases? > - What should I consider when choosing between apache2 and nginx? > > We may have some of this material in the intro sections of some portions > of the guide (and I see you've linked several of these pages there, so > guess you may be of similar mind), however I wonder if it may be more > manageable to start with the Explanation section empty and populate it > by extracting the more "discussion" oriented sections of the current > docs. > > > A lot of the server guide content is structured per-package, as you > pointed out. That translates well for Reference material (esp. if we > pull from upstream), and for Tutorial (where the user needs to start > small) but with How-To Guides things get blurry. Particularly for > topics that go beyond installation and basic configuration, tasks are > often going to involve more than one piece of software. For example > setting up kerberos for a file server, or credentials for SSL support, > or a database for a webserver. So the How-To section might be better > structured on a more per-task basis. > > > One other advantage of putting all the current docs into one section > (e.g. Tutorials) and extracting, is that it may take quite a while to > process through the docs and that would allow the collection to be in a > cohesively usable state from the start. I'd worry if we split up intro > pages for the sections from the package-specific pages too early in the > process, it may fragment the whole to a degree it becomes too confusing > for users to use.
I'm also not a fan of too much splitting. Most of the "Tutorial" we have are actually just How-To. The "Reference" we have is usually just link to upstreams references. Both of those weak Tutorials and References are not worth a split page in most cases. But resolving this imbalance this is part of the long term big effort to integrate e.g. upstream references and other doc sources than what we wrote in discourse. Not the current work. In any case if we split (and some we will or your effort makes not much sense), then I believe we will need some kind of meta-index that provides the old style "per workload" way to reach things. Is that even possible? > Thanks again Lena for putting time into this reorganizing. I can > envision down the road when things are fleshed out and filled in, this > may become a great resource for people. > > Bryce > > -- > ubuntu-server mailing list > ubuntu-server@lists.ubuntu.com > https://lists.ubuntu.com/mailman/listinfo/ubuntu-server > More info: https://wiki.ubuntu.com/ServerTeam -- Christian Ehrhardt Senior Staff Engineer, Ubuntu Server Canonical Ltd -- ubuntu-server mailing list ubuntu-server@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
