Hello Ingo, Theo, all, Thanks for taking the time to respond to my mail, I understand & agree with many of your points made, the ones I disagree with I will discuss with you over a Pint of Beer or 2, at some conference :)
Ill take on board your suggestions of lots of little edits / little patches as opposed to large re-works of manuals / docs. Both of your inputs allow me to make a start at it ...and we will take it from there. We can revisit the possibility of tutorials (Not How Tos)once my understanding and documentation ability improves and that I can formulate a proposed approach that the team would would be happy with. (but this is clearly some way down the road) Thanks again and any other suggestions and tips welcome PS @Ingo Appreciate the pointers to your slides on mdoc(7) On 8 August 2017 at 03:48, Ingo Schwarze <[email protected]> wrote: > 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
