Are you sure? The wikibook? I only see their books there.
Not the wikibook. Hereâs the link.
OK, but @flexibeast said
As some context for my comments here, iâd like to note that most of my volunteer IT time nowadays is spent on creating and updating documentation (rather than on coding, as it used to be), and i do lots[ of work in this regard.
Currently, most of my work is focused on the improving the Gentoo wiki: here are my contributions so far, which includes creating and developing the âAdaâ page. Previously, i made significant contributions to the Void Linux documentation. iâm also the porter and maintainer of man page ports of the documentation for many parts of the s6 ecosystem.
Consequently, i have some fairly strong opinions about documentation. 
The wikibook was never thought as a material which you could read from first chapter to last chapter, but more a reference and self-directed learning, so it depends more on the hyperlinks to define things, rather than giving a predefined learning path.
Well, to me, thatâs a wiki, not a wikibook. The former has no suggested reading order; the latter does. In particular, a âbookâ of IT documentation - even a reference work - is generally expected to be structured such that more fundamental things are introduced prior to the things that reference or build on them.
And indeed, it seems to me that the âProgramming in Adaâ section is generally structured that way, with the lists strongly suggesting a specific order of reading.
In a âbookâ, a suggested order of reading is necessary for beginners, who donât yet have the knowledge to determine what things they need to learn and understand before they try to learn and understand other things. This is particularly the case for Ada, whose vintage means that it has concepts and terminology that are ânon-standardâ from a contemporary point of view. (GNU Emacs has a similar issue: e.g. it talks of a âframeâ for something most people think of as a âwindowâ, and a âwindowâ is something inside a âframeâ, because its initial release was around the same time i was learning BASICs on 6502s.)
Consequently, Iâve added a definition to that section and a link to the corresponding page in the book.
Thank you, much appreciated.
Remember that the Wikibooks is open for anyone to edit, so if you have ideas about how to improve it, you are more than welcome to edit it.
This is one of the issues about which i have strong opinions.
Clearly iâm someone whoâs very much willing to help provide and improve documentation. However, i find it problematic how often itâs suggested to beginners to a system / language / application etc. that they âfill in the gapsâ. As iâve written elsewhere:
Someone reaching for documentation is doing so because they donât know how to use some software, whether an application or a library. Since they donât know how to use the software, they are not able to document how to use it!
Presumably the idea is that application users should faff around, experiment, find what works and what doesnât. And that library users should do the same, or read the library source. There are a few problems with this:
- The usual reasons the user has reached for the software is because they feel itâs going to help them Get Something Done, or because theyâve been forced to use it by the-powers-that-be - not as an end in itself. Someone frustrated by not being able to progress their task due to lack of documentation is unlikely to have their frustration reduced by being told to go off-task.
- Users might come up with a solution, but that doesnât mean it should be documented: that solution might not be idiomatic, or indeed, it might be actively dangerous. This is exemplified by users who, when faced with permissions issues on nx-ish systems, âsolveâ the problem by setting files (or entire directory trees!) mode 777, sometimes creating massive security holes.
- The source might be written in a language with which the user isnât familiar - cf. many programming languages providing âwrapperâ APIs around C libraries.
The sorts of issues raised by the second-to-last point were why Void abandoned its wiki, and moved to a repo-based approach - people were adding incorrect stuff that the Void team didnât have the resources to be continually checking for.
The first point is particularly relevant in the context of this thread. Weâre discussing the various obstacles, great and small, that limit the extent to which beginners adopt Ada. Someone wrestling with toolchains and concepts and terminology and new ways of doing things - even when theyâre things whose benefits are a reason to learn Ada - is not necessarily in the best place for making wiki edits, or having it suggested to them that they do so.
The argument can be made: âBut beginners know what stuff is missing, which those of us with more experience have been taking for granted!â This is true, but it doesnât inherently imply that they should therefore be the people filling in those gaps. Itâs like someone saying âI found I couldnât use Ada for the things that I wanted because it seems to lack libraries for doing X and Yâ, and being told âContributions welcome.â Okay, but thatâs not actually addressing the obstacle that the dev faced and encouraging them to continue with the language; itâs effectively saying âIf you want to use this language, youâll have to take on extra work outside of the actual stuff youâre wanting to do.â And it can discourage feedback, because it can cause people to think âMeh, if I take the time to point out this issue, I might just get told to fix it myself, so why waste my time pointing it out.â
(Certainly for myself, given the extent to iâm working on documentation, and raising and fixing bugs, and how i actually tend to over-commit in this regard, i do feel itâs not unreasonable for me to not have to be responsible for being the one to resolve any issue i raise.)
Finally, i acknowledge that many, if not most of us, who are working on this sort of stuff are doing so as volunteers. So itâs up to us to choose what we do and donât want to work on, and in the end i can only suggest things that i feel would improve the UX of readers/users/devs. Still, as i also wrote elsewhere:
Some devs make the argument that if they spent their time writing documentation, they wouldnât have as much time to work on the software itself, or that if they had to write documentation, it would decrease their enthusiasm for working on the software overall[a]. Okay; they get to choose how to spend their time. But that doesnât necessitate telling users to write the documentation themselves! Devs could simply say e.g. âI find working on documentation to be too much of a chore, sorry.â And preferably: â⊠but Iâll try to support you if youâd like to work on it yourself.â (As someone who can actually like writing documentation, iâve found it frustrating when i try to do so for a given project, only to face a lack of concrete support from the relevant dev(s).)
At any rate, i use a devâs attitudes towards documentation as something of a measure of how supportive they are of users, and the extent to which i should rely on their software. A dev who would rather avoid spending five minutes on writing documentation, rather than effectively forcing five users to each spend five minutes trying to work out how to do something, certainly has the right to do so; but then i have to weigh up whether the benefits of using their software will outweigh the possible costs when the software becomes a hindrance rather than a help.
âŠ
[a] And there are possibly other reasons as well:
"The vast majority of my time as a documenter of groff is spent on the discipline of crafting English, not markup.
âBut you canât get this message through to a lot of people. Writing English doesnât seem to them like something that will impress anyone reading their rĂ©sumĂ©. And, to be sure, for a lot of the people theyâre trying to get jobs from, theyâre right.â
â manual section titles (was: All caps .TH page title)
4 Likes
By the way, where is that EPUB version located? I hope it has preserved hyperlinks, otherwise the book loses a lot of value.
Oh, sorry! Itâs actually not an EPUB, but a PDF, which is here, and linked to at the start of the âProgramming in Adaâ section. Even though i was initially accessing the wikibook directly on the site, i downloaded the PDF so that i can read it on my Kobo e-ink reader, which is a lot more comfortable for me for long-form reading, and which doesnât require me to be online.
Unfortunately, links are indeed not preserved by the relevant PDF generation process.
Yes, probably that is not a good idea in general. Some years ago, it might make sense to remember users that they can edit a wiki themselves, but nowadays, everyone already knows and if they havenât done it themselves for good reasons, it is counterproductive to remember them so.
That file was the semi-automated work done by some contributor, using LaTeX from the wiki source text. There is also the automatically generated PDF by Wikibooks software. We should probably evaluate if linking to this automatic generation would be better than to the LaTeX version. In any case, Iâm going to update the current LaTeX version, which should be easy with https://mediawiki2latex.wmflabs.org
Edited: it wasnât possible, with that web and either with a local installation of mediawiki2latex, due to lack of enough free memory. I guess the wikibook has grown or it was generated in a machine with more RAM.
1 Like