From mboxrd@z Thu Jan 1 00:00:00 1970 From: dnl To: documentation@lists.ipfire.org Subject: Re: IPS Rule selection page Date: Sat, 27 Jul 2019 16:31:07 +1000 Message-ID: <682fe66e-82bb-2234-06e6-998862197d38@runbox.co> In-Reply-To: MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="===============0764750675974360810==" List-Id: --===============0764750675974360810== Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Hi Michael, Thank you for your reply and feedback. While helpful, your email made me feel frustrated.=C2=A0 You and I both seem = to have strong opinions on things and it feels like our opinions are=20 often opposing!=C2=A0 I had actually given up on writing any more=20 documentation, but have come back to this after some thought.=C2=A0 Hopefully= =20 we can come to some common ground and you might explain your thinking on=20 some things. For some background I also write technical documentation as a part of my=20 profession (amongst other things). >> On 10 Jun 2019, at 06:29, dnl wrote: >> >> Hi all, >> >> I recently spent some time totally rewriting and fleshing-out the IPS rule= selection wiki page: https://wiki.ipfire.org/configuration/firewall/ips/rule= -selection. >> >> The iterative approach to choosing IPS rules is a difficult subject to put= in to words succinctly and I feel the page has become very long and wordy. > I agree with that approach and I think you have a good start there, but the= page is indeed way too long. > > I think this because you are giving (almost too many) examples. You mention= Heartbleed which is very specific and entirely irrelevant. We can assume tha= t people know what a vulnerability is. If not, people should not be managing = their own IPS. While I suggested the page is too long, I feel that you are perhaps=20 suggesting the opposite extreme here. Writing a complex subject in a short document is not helpful to=20 readers.=C2=A0 Being succinct and clear with a complex subject is but can=20 still cause a document to be quite long.=C2=A0 I feel some initial IPFire=20 documentation has been too short and did not clearly convey complex=20 topics even to technical readers.=C2=A0 It is a disservice to those who do=20 bother to read before asking questions in the forums. > Then, you are adding those boxes. The new wiki won=E2=80=99t support those = any more. They stop the flow in reading and we have a pages where apparently = everything seems to be a super important information. That makes nothing high= lighted at all. I read a lot of professional documentation and the sparing use of info=20 and warning boxes is an invaluable way of communicating clearly,=20 especially when you really need the reader to read that information.=C2=A0=20 While you might argue this page too many, entirely taking away the boxes=20 from a wiki is short-sighed. I've seen wikis which didn't have them and the first thing people did=20 was create single celled tables and add an exclamation mark icon - so=20 they have a warning box back! (I don't want to fight you over this, so=20 wouldn't do it unless you permit it.) > Then you copy a lot of content. For example what should be enabled in the E= T ruleset. I had that at the bottom of the page. Not very much in-depth, but = if you want to have more detail, I think it is best to make an extra page whe= re we explain the individual rulesets. Maybe there are some resources out the= re on the internet that we can link? Thanks - good idea. > Also, please don=E2=80=99t use lists to separate paragraphs. Lists are a clear way of displaying information briefly or for=20 emphasising things to save readers time.=C2=A0 Writing everything in=20 paragraphs is not ideal in technical documentation, sometimes points=20 need to be displayed. I tend to write significant points and then expand on them in a=20 paragraph beneath.=C2=A0 This way a reader can choose to skip the explanatory= =20 paragraph if they already understand something from the basic bullet=20 point.=C2=A0 (I suppose you could compromise by using the "expandable"=20 sections some wikis like Confluence have) Perhaps you could write a style guide for how you would prefer pages to=20 look?=C2=A0 That would really help me understand. > I would prefer to try to shorten the page again and move examples onto a se= parate page. What's your concern about long pages please?=C2=A0 I see that you don't like = a table of contents on each. You're not making money from ads/page impressions so what's the drive=20 for many short pages?=C2=A0 If people do not finish reading a long page=20 they're not going to read a linked page either, so I don't understand=20 what difference there is between long and many pages. Perhaps a style guide could explain this point too? Anyway I ended up splitting the Security Hardening guide after reading=20 your email.=C2=A0 It's the kind of document which someone will probably read = entirely or not read at all.=C2=A0 Hopefully my changes make it in to the new= =20 wiki (I've not had time to check). > So, all in all I think you have many very good thoughts in there. But I agr= ee that the page is way too long. It needs to be split (see my suggestion abo= ve) and I think the content that is there can be made a little bit shorter. W= e can assume enough knowledge of the reader to get basic concepts. The exampl= e that you won=E2=80=99t need BSD rules when you don=E2=80=99t have BSD syste= ms on your network can be half a sentence. People should be able to get a hin= t. Thank you for the feedback. > > Otherwise we might run into people not reading this at all and therefore mi= ssing basic principles when configuring this. Who reads a page of text these = days? > > -Michael Perhaps I'm rare because I do read most documentation! This is why I like bullet points over multiple paragraphs.=C2=A0 An impatient= =20 reader may read bullet points when they wouldn't bother to digest a=20 whole paragraph. I'd really love to see IPFire have documentation for every option on=20 every UI page.=C2=A0 This is partly so that in future there could be a help=20 link on every UI page to that documentation.=C2=A0 Today you have to search=20 the wiki for an option as the option text may not be explicitly=20 mentioned.=C2=A0 Also not every option is explained in documentation yet,=20 which forces users to experiment or write (potentially unnecessary)=20 questions in the forums. Finally, could you please do a final import from the old wiki before=20 moving to the new one?=C2=A0 I think a lot of us make small, but frequent=20 updates. Thank you, dnl --===============0764750675974360810==--