Hi Tom, you are aware that the term "HOWTO" is very strongly detested round here, right? It is considered a synonym for so-called documentation that is imprecise, unsystematic, and tells the user to type some random commands they won't understand because the HOWTO doesn't really explain how things actually work.
Tom Smyth wrote on Mon, Aug 07, 2017 at 11:46:46PM +0100: > Im currently working on internal training documentation for > our operations and field teams for dealing with OpenBSD based > equipment. These documents would focus on OpenBSDs Network stack > and its capabilities, diagnostics and configuration manipulation It would probably be hard to pick an area where working on the documentation is harder than in the vicinity of the network stack. Some important manual pages in that area are below-average quality both regarding content and markup (including pf.conf(5) and ifconfig(8)), and that is not a coincidence: The subject matter is unusually difficult, the number of features to explain is unusually large, the number of people qualified to judge the accuracy of the manual pages and proposed changes is unusually small, and many of them are unusually busy. > Since Im going to that trouble I thought maybe my effort could > be aligned with the goals of the project, As a matter of principle, OpenBSD documentation is reference documentation. So if you want to help the project, that would mean improving manual pages (or maybe occasionally the FAQ, but much less frequently). Both aim for exactness and conciseness above all else, so writing substantial amounts of new text is unlikely to help. > and perhaps reduce the workload from some of the developers I'm not aware of any developers who currently spend significant time on network stack documentation, so the effect would be improving documentation, not reducing workload. But that is fine, we consider documentation important. It will *increase* the workload on the developers in question because they will have to check your diffs - jmc@ and myself will usually be unable to do that alone because we don't understand the network stack well enough. > advocates of the OpenBSD Project. I'm not aware of the existance of advocates, and there are certainly no advocates who work on documentation. > I was discussing this with some developers at BSDCan but I didnt > come away with a clear view of how to approach it. Give the manual pages to your field engineers as training documentation for specific tasks, see how they fare with them, and if they fail to set things up properly, figure out why. If the reason is that they don't read carefully enough (being used to low-quality documentation), work with them to improve their reading skills. If the reason is that some features are not described, or with too little precision, or wrongly, send patches to fix the gaps and bugs. If the reason is that everything is described exactly but the subject matter is so complicated that assembling actual commands or configuration from the description alone is very hard, work on adding or improving examples, focussing on *conciseness*. In any case, the shorter the patches you send, the better. Anything containing long newly-written text is probably of little use, at least until you will have collected a lot of experience working on OpenBSD documentation. It seems likely to me that all three elements will be needed, and that both the first and the second will require more time and effort than the third. > Could the members of OpenBSD who are responsible for OpenBSD > Documentation, and indeed anyone who is interested in advancing / > improving the documentation of OpenBSD get in touch so that I can > adopt an approach that is compatible with the overall direction of > the project and that I can finally provide practical support for > a project that I have benefited from for so long. There is only one way. Get started, find bugs and gaps in the manual pages, send patches (to tech@ or to developers who you know are interested), gain experience that way, and consequently improve the quality of your patches over time. > My initial thinking is > 1) learn mandoc You mean mdoc(7), probably. That certainly cannot hurt, but don't waste too much time on that, focus on *content*. When you send patches, people like jmc@ and myself will point out markup details to you, and then you can read up on the pieces you actually need. Also, mdoc(7) isn't all that difficult. If you want, look at the slides 15 to 21 of my Sofia EuroBSDCon talk: http://mandoc.bsd.lv/press.html (2014 Sep 26) and if you want, look at slides 1 to 13 for a general background. But the markup language isn't critical, really. > 2) work with interested parties who would like to see some concept > driven / example driven documentation I don't have the slightest idea what you are talking about. I'm not aware of any such parties. > 3) I really like the snappy slick presentation of the training slides > at http://www.openbsdjumpstart.org I consider that mostly useless. It doesn't really explain anything. Well, the references to the manual pages may be helpful, but a plain-text list could serve the same purpose. So building that site was mostly a waste of time. > If someone has templates for creating training slides / that rely > only on HTML and CSS /usr/src/usr.bin/mandoc/mandoc.css https://man.openbsd.org/mandoc.css > I would love to use those to create HTML help pages as well > as man pages. That makes no sense at all. Do not create separate HTML documents. Create the HTML version of documention from the manual pages with mandoc -Thtml or man.cgi(8). > in a nutshell Im writing content anyway... Do not focus on writing content. Focus on small improvements. Filling gaps, improving exactness, removing bugs, making wording clearer and shorter and terminology more uniform, and the like. And of course help people to learn reading good manual pages. Yours, Ingo
