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@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