Re: IPS Rule selection page

[dnl <dnlipfire@runbox.co>]

[-- Attachment #1: Type: text/plain, Size: 6074 bytes --]

Hi Michael,

Thank you for your reply and feedback.

While helpful, your email made me feel frustrated.  You and I both seem 
to have strong opinions on things and it feels like our opinions are 
often opposing!  I had actually given up on writing any more 
documentation, but have come back to this after some thought.  Hopefully 
we can come to some common ground and you might explain your thinking on 
some things.

For some background I also write technical documentation as a part of my 
profession (amongst other things).
>> On 10 Jun 2019, at 06:29, dnl <dnlipfire(a)runbox.co> 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 that 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 
suggesting the opposite extreme here.

Writing a complex subject in a short document is not helpful to 
readers.  Being succinct and clear with a complex subject is but can 
still cause a document to be quite long.  I feel some initial IPFire 
documentation has been too short and did not clearly convey complex 
topics even to technical readers.  It is a disservice to those who do 
bother to read before asking questions in the forums.

> Then, you are adding those boxes. The new wiki won’t 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 highlighted at all.

I read a lot of professional documentation and the sparing use of info 
and warning boxes is an invaluable way of communicating clearly, 
especially when you really need the reader to read that information.  
While you might argue this page too many, entirely taking away the boxes 
from a wiki is short-sighed.

I've seen wikis which didn't have them and the first thing people did 
was create single celled tables and add an exclamation mark icon - so 
they have a warning box back! (I don't want to fight you over this, so 
wouldn't do it unless you permit it.)

> Then you copy a lot of content. For example what should be enabled in the ET 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 where we explain the individual rulesets. Maybe there are some resources out there on the internet that we can link?
Thanks - good idea.
> Also, please don’t use lists to separate paragraphs.

Lists are a clear way of displaying information briefly or for 
emphasising things to save readers time.  Writing everything in 
paragraphs is not ideal in technical documentation, sometimes points 
need to be displayed.

I tend to write significant points and then expand on them in a 
paragraph beneath.  This way a reader can choose to skip the explanatory 
paragraph if they already understand something from the basic bullet 
point.  (I suppose you could compromise by using the "expandable" 
sections some wikis like Confluence have)

Perhaps you could write a style guide for how you would prefer pages to 
look?  That would really help me understand.

> I would prefer to try to shorten the page again and move examples onto a separate page.

What's your concern about long pages please?  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 
for many short pages?  If people do not finish reading a long page 
they're not going to read a linked page either, so I don't understand 
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 
your email.  It's the kind of document which someone will probably read 
entirely or not read at all.  Hopefully my changes make it in to the new 
wiki (I've not had time to check).

> So, all in all I think you have many very good thoughts in there. But I agree that the page is way too long. It needs to be split (see my suggestion above) and I think the content that is there can be made a little bit shorter. We can assume enough knowledge of the reader to get basic concepts. The example that you won’t need BSD rules when you don’t have BSD systems on your network can be half a sentence. People should be able to get a hint.
Thank you for the feedback.
>
> Otherwise we might run into people not reading this at all and therefore missing 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.  An impatient 
reader may read bullet points when they wouldn't bother to digest a 
whole paragraph.


I'd really love to see IPFire have documentation for every option on 
every UI page.  This is partly so that in future there could be a help 
link on every UI page to that documentation.  Today you have to search 
the wiki for an option as the option text may not be explicitly 
mentioned.  Also not every option is explained in documentation yet, 
which forces users to experiment or write (potentially unnecessary) 
questions in the forums.

Finally, could you please do a final import from the old wiki before 
moving to the new one?  I think a lot of us make small, but frequent 
updates.


Thank you,

dnl