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 <schwa...@usta.de> 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

Reply via email to