Wiki Updates / Style Guidelines
-
Over the last few months I have worked through nearly every article in on our documentation wiki, https://doc.pfsense.org/ , editing for content, consistency, formatting, grammar, and so on.
Some articles have been updated for 2.2 (or at least 2.1.5), and some really old information was removed/cleaned up if it was no longer needed. A few things were rearranged, and some longer articles have been split up into smaller chunks. Quite a few new articles have also been added and there are more on the way.
Due to the large amount of work that has been put into cleaning up the Wiki and making corrections, the following is very important:
If you currently have an account to edit articles on the documentation wiki, please review the style and content guidelines before making any future edits to ensure that all articles continue to be of high quality and reflect well on the project.
Wiki Style Guide - https://doc.pfsense.org/index.php/Wiki_Style_Guide
Please read this entire article and follow the rules on the page. They are fairly simple guidelines but make a big difference in how articles look and read. Things like making sure "pfSense" is always properly capitalized, never addressing the user ("you", "your", etc.) and so on.Quality Guidelines - https://doc.pfsense.org/index.php/Quality_guidelines
This article covers what should and should not be found in articles.Templates - https://doc.pfsense.org/index.php/Template
Handy templates to add to articles to improve their appearance or make certain tasks easier.Articles that do not follow the style and quality guidelines may be edited, removed, or flagged for cleanup.
If you notice an article that has a mistake or is in need of some other correction, bring it to our attention.
-
Will take a look see, thanks!
-
Thanks, jimp.
The style guide and templates are a great idea.
I did think a lot about which way to go regarding the use of the first and second person, etc.Ā There didn't seem to be much in the way of rules, so I just kept going in the hope of actually finishing my one and only contribution, while trying to figure out mediawiki formattingĀ ::).
I'll try to fix the screen shots (and maybe rework the first person stuff, as well)Ā in the very near future.
Edit: At least you didn't insist on _pfSense_
Ā :) -
I've been trying to use them here, too.Ā I particularly like the italics for user entered content.Ā Beats using quotes.Ā (Do I enter the quotes or not?)
-
The style guide and templates are a great idea.
The style guide is new but the templates have always been there (most of them, anyhow) ā funny thing though, even I had no idea that Templates page existed until I stumbled across it during this batch of updates :-)
I did think a lot about which way to go regarding the use of the first and second person, etc.Ā There didn't seem to be much in the way of rules, so I just kept going in the hope of actually finishing my one and only contribution, while trying to figure out mediawiki formattingĀ ::).
If you click "edit" on the style guide page the formatting is all there to see, which should be a handy reference for everyone to have in one spot.
I'll try to fix the screen shots (and maybe rework the first person stuff, as well)Ā in the very near future.
I fixed the wording/language on that page already, I think it just needs new screen shots to match the current wan=em0 lan=em1 recommendation.
-
I've been trying to use them here, too.Ā I particularly like the italics for user entered content.Ā Beats using quotes.Ā (Do I enter the quotes or not?)
Much of this was inspired by how we code the book in docbook. There aren't direct equivalents in mediawiki for most things like <replaceable>or <userinput>but we can use similar concepts. Along with being much easier to follow, It helps the book and wiki look more consistent.
And it definitely beats the ambiguous nature of quotes, so we don't have to constantly say things such as:Ā Enter "foo" (without quotes)</userinput></replaceable>
-
This a great step forward in documentation. There are some things in the style guide that would not have chosen to do but in the end having some consistency is much better.
I have to say that reading through the list and comparing it to only page I contributed did seem like a check list of mistakes. Time for some editing.Ā ::)My only comment here might be that the first time I went to the Writing_Disk_Images page after if had been updated I completely missed the [Expand] buttons and ended up thinking there was actually less information there. Perhaps they could be enhanced somehow?
Steve
-
This a great step forward in documentation. There are some things in the style guide that would not have chosen to do but in the end having some consistency is much better.
Such as? Always open to suggestions.
I have to say that reading through the list and comparing it to only page I contributed did seem like a check list of mistakes. Time for some editing.Ā ::)
I'm the biggest offender of all, I started the style guide while correcting things I'd done over the last 6+ years so I'd have a list of things to check/look out for. It was a lot of work but I think there are only a single digit number of articles left that may not quite conform.
My only comment here might be that the first time I went to the Writing_Disk_Images page after if had been updated I completely missed the [Expand] buttons and ended up thinking there was actually less information there. Perhaps they could be enhanced somehow?
That would have to be changed in the CSS, I think. There may be other classes/styles that could be added which already exist. I've tried using some extra bits in the style tag but nothing seemed to help that. Suggestions welcome. After 2.2-RELEASE I can bug one of our web devs about it.
-
Such as? Always open to suggestions.
Well off hand I have always used the following notation when referring to a page in the webgui:
System: Advanced: Networking:
Only because that's how it appears in the webgui when you get to the page. However using:
System > Advanced, Networking tab
implies navigating the menus in order more correctly. It's far better to have consistency even it's not everyones preferred option, as long it's not actually incorrect in some way.
Steve
-
Ah, yes, the style I used focuses on the navigation actions taken by the user. The page titles don't always line up or may have longer titles. The page titles are more free-form and less restricted by space than the menus, but when instructing the user what to click or where to go, it's preferred to list the items they should be clicking on.
So the page titles are more informative, but less useful as a navigation aid.
