[Slackdocs] Page guidelines
David Demelier
markand at malikania.fr
Thu Feb 21 12:12:29 CET 2019
Hello,
It looks like there are many different writing styles on the wiki. I
think we should uniform that a bit.
1. Page names
=============
Let's keep them simple, examples:
- install_mariadb_on_slackware: BAD, the wiki is about slackware, so
"on_slackware" is redundant. Also, installing makes the page too
restrictive. What if the page adds much more documentation than just
installing?
- postgresql: GOOD, generic and future-proof.
I already renamed some pages, I'd to hear if you agree or not. But I
think it really needs a big cleanup.
2. Page groups
==============
Like the statement above, the following page could have been merged into
one "firefox"
- firefox_annoyances
- firefox_downloaded_files
- firefox_pdf_viewer
Having too much split pages makes the index and searching too
complicated. I'll merge them myself.
3. Page templates
=================
It could be very nice if all pages under a specific namespace follow the
same template. Example in howtos:software
====== Introduction ======
Short summary
====== Installation ======
Short summary
====== Usage =======
For this, I propose that all namespaces contain a template file to follow:
- howtos
- software
- template
- security
- template
And such. Obviously, if you agree I'll do it myself and update pages
accordingly.
4. Guidelines
=============
As guidelines I propose:
- pages names are always lowercase_with_underscore
- pages names must match a generic term if possible
- pages names must follow the appropriate template file
I think we should add a paragraph about that on the page:
https://docs.slackware.com/slackdocs:tutorial
I don't have write access on it, could you please write one?
Regards,
--
David
More information about the Slackdocs
mailing list